Structured Autonomy Teach

The document MUST:

• Explain every concept used — assume the reader has no prior knowledge of the specific technologies applied
• Reference actual file paths, function names, and code snippets from the implementation
• Include diagrams (Mermaid) or formulas (KaTeX) wherever they aid understanding
• Contain NO [NEEDS CLARIFICATION] markers — all sections must be fully populated
• Be readable by an engineer who was not involved in the implementation
• Do NOT pause for user feedback — produce the full document autonomously

<research_guide>

Research the completed feature implementation comprehensively:

1. Read Artifacts:

   • Read plans/{feature-name}/plan.md in full — extract the feature goal, branch name, and every implementation step
   • Read plans/{feature-name}/implementation.md in full — extract all file paths, code blocks, and verification steps

2. Inspect Changed Files:

   • Open every source file listed in implementation.md and read its current state
   • Identify all libraries imported, algorithms used, data structures defined, and design patterns applied

3. Concept Extraction:

   • List every distinct concept that appears (e.g. specific algorithms, data structures, design patterns, framework features, mathematical formulas, language idioms)
   • For each concept, note: where it appears in the code, why it was chosen, and what alternatives exist

4. Design Decision Mining:

   • For each architectural or structural choice made (class hierarchy, data layout, API shape, file organization), identify the decision and reconstruct the rationale from the plan and the code

5. External Research:

   • For any library, framework, or algorithm referenced, fetch official documentation or reputable sources to gather precise definitions and best-practice guidance
   • Note version-specific behavior, known gotchas, and limitations

Stop research when you have enough material to populate all six sections of the output template with concrete, specific content.

</research_guide>

<output_template>

File: plans/{feature-name}/theory.md

# {Feature Name} — Theory & Background

**Feature branch:** `{kebab-case-branch-name}`
**Implementation plan:** `plans/{feature-name}/implementation.md`

---

## 1. Background & Context

> *What problem does this feature solve, and why does it matter?*

{2–4 paragraphs describing the problem domain, the motivation for building this feature, and the value it delivers. Reference the Goal section from plan.md. Mention any prior state of the codebase that made this feature necessary.}

---

## 2. Core Concepts

> *The theory behind every key technology, algorithm, or data structure used.*

{For each distinct concept identified during research, write a subsection:}

### 2.1 {Concept Name}

{Plain-language explanation of what the concept is. Include a diagram or formula if it aids understanding.}

**Where it appears in the code:** `{file path}` — `{function or class name}`

**Why it was chosen:** {rationale}

**Alternatives considered:** {what else could have been used and why it was not}

{Repeat for each concept: 2.2, 2.3, ...}

---

## 3. Design Decisions

> *Rationale for every architectural and structural choice made during implementation.*

{For each significant design decision:}

### Decision: {Short decision title}

**Choice made:** {What was decided — e.g., "Used a dictionary keyed by section ID rather than a list"}

**Rationale:** {Why this choice was made — performance, clarity, extensibility, constraints, etc.}

**Trade-offs:** {What is sacrificed or complicated by this choice}

{Repeat for each decision}

---

## 4. Techniques & Patterns

> *Coding patterns, best practices, and idioms applied in the implementation.*

{For each pattern or technique:}

### {Pattern Name}

**Description:** {What the pattern is and how it works in general}

**Applied in:** `{file path}` — snippet:
```{language}
{Short representative code excerpt from the actual implementation}

Benefit: {Why this pattern was the right fit here}

{Repeat for each pattern}

5. Gotchas & Pitfalls

Edge cases, known limitations, and things to watch out for when working with or extending this code.

• {Gotcha title}: {Description of the issue, when it occurs, and how to handle it}
• {Gotcha title}: {Description}
• {Add as many as relevant — minimum 3}

6. Further Reading

Resources for going deeper on the concepts covered in this document.

</output_template>