Content authoring standard

This repository is a gap-driven reference for experienced PHP and Laravel developers. It is not a course, an API catalogue, a grading system, or a substitute for primary documentation. Expansion work is done as complete topic bundles so that reference material and interview practice cannot drift apart.

Page states

Every core reference page uses one status immediately below its title:

• > **Status:** Outline. — scope notes or prompts, not yet reliable as a complete reference.
• > **Status:** Concise draft. — useful existing material that predates the expansion contract and still needs a full bundle pass.
• > **Status:** Complete. Last reviewed YYYY-MM-DD. — satisfies this standard and has matching canonical questions and answers.

Optional pages may use Optional outline or Optional when their position outside the core roadmap matters. Do not infer completion from the absence of an Outline marker.

Topic bundle

A bundle owns all of the following:

1. One reference page with a precise mental model and production depth.
2. Four to six canonical questions in the appropriate topical interview file.
3. One keyed, collapsible example answer for every new question.
4. Links from the reference page to the canonical question anchors.
5. Primary-source links for claims that can change with a release.
6. Validation and one focused commit.

Reference pages own explanations. Interview files own questions. Cross-topic banks own indexes and curated mock-interview sets; they link to canonical questions instead of copying their text.

Reference-page structure

Use these sections when they clarify the topic, combining adjacent sections when that reads better:

1. Precise mental model — name the abstraction and define what it does and does not guarantee.
2. Mechanism — trace the important runtime behavior, ordering, state, or data flow.
3. Commonly confused concepts — contrast similar terms by responsibility and consequence.
4. Production consequences and failure modes — explain how incorrect assumptions appear in logs, latency, data, or operations.
5. Alternatives and trade-offs — give decision triggers, not blanket preferences.
6. Current and legacy context — use the labels in the version guide.
7. Focused example or failure timeline — include code only when observing behavior adds understanding.
8. Interview practice — link the stable IDs in the canonical interview file.
9. Primary sources — link durable official documentation or specifications near version-sensitive claims.

A completed core page should normally contain 1,200–2,000 words, excluding linked interview answers. A shorter page is acceptable only when additional prose would duplicate another page or turn into an API inventory. Split a page when distinct mechanisms would make it materially exceed that range.

Writing constraints

• Assume the reader already ships software. Summarize basics briefly or link to primary documentation.
• Prefer causal explanations: state what happens, why it happens, and what evidence would reveal a bad assumption.
• Separate framework behavior from an application convention and a team preference.
• Use concrete failure modes, assumptions, and revision triggers instead of slogans.
• Avoid exhaustive method lists, installation walkthroughs, trivia, and invented benchmark numbers.
• Keep generic backend concepts in engineering/ and link from framework pages rather than repeating them.
• Keep framework-specific behavior in laravel/; keep language/runtime behavior in php/.
• Focused examples are welcome. Do not add a sample Laravel application solely to demonstrate prose.

Canonical questions and answers

Stable IDs use an uppercase domain and topic, followed by a two-digit sequence, for example LARAVEL-LIFECYCLE-01. IDs never change after publication; wording may be clarified without changing the ID.

All questions appear before a final ## Example answers section. Use an explicit HTML anchor so links remain stable if a heading changes:

<a id="LARAVEL-LIFECYCLE-01"></a>
### LARAVEL-LIFECYCLE-01 — Trace a web request

Trace a current Laravel web request from the front controller to the emitted response.

At the bottom of the same file, pair it with one details block:

<details>
<summary>LARAVEL-LIFECYCLE-01 — Example answer</summary>

An example 60–120 second spoken response goes here.

</details>

Answers demonstrate one credible response, not a rubric or uniquely correct script. Prefer natural spoken prose. A senior answer should identify relevant assumptions, failure modes, evidence, and decision triggers. Every published ID must have exactly one question and exactly one answer.

Source policy

Use primary sources for current or version-sensitive claims: official PHP and Laravel documentation, framework source, standards, database-vendor documentation, or recognized protocol and security specifications. Secondary sources may inspire an explanation but should not be the authority for a claim that can age.

Prefer durable documentation entry points. Link framework source only when implementation detail materially supports the mental model. Record Last reviewed on completed pages; do not claim that a version is current without checking it during the bundle.

Bundle validation

Before marking a bundle complete:

• confirm the page follows the content contract and no longer says Outline or Concise draft;
• confirm it contains four to six links to canonical stable question IDs;
• confirm every question precedes ## Example answers and has one matching <details> block;
• search the repository for duplicate IDs and duplicated canonical question text;
• check version-sensitive claims against current primary sources;
• run PHP syntax checks and execute focused examples when applicable;
• resolve all internal Markdown links;
• run git diff --check;
• update the roadmap handoff with the completed commit (or pending commit before committing), next bundle, and immediate next action;
• make one focused commit without absorbing unrelated user changes.

The roadmap tracks repository authoring state only. It must never be used to grade or track a reader’s learning progress.