@vpxa/aikit 0.1.74 → 0.1.76

package/scaffold/_preview/skills/docs/references/diataxis-anti-patterns.md

@@ -1,147 +0,0 @@
-# Diátaxis Anti-Patterns
-
-Five common documentation anti-patterns that violate Diátaxis quadrant boundaries. Each pattern includes detection signals, a violation/compliant example pair, and remediation.
-
-## Anti-Pattern 1: Tutorial with Explanation
-
-**Detection signals:** "This is because...", conceptual paragraphs between steps, "Let's understand why..." mid-tutorial.
-
-**Failure mode:** Learner loses momentum; cognitive load increases; tutorial becomes reference-like.
-
-**Violation example:**
-
-> Step 4: Exchange the authorization code for a token.
->
-> The authorization code grant exists because the client and server need a temporary credential that can be verified before issuing a bearer token. In OAuth 2.0, this protects the user agent from exposing long-lived credentials and supports redirect-based trust establishment. The protocol also separates authentication from authorization, which matters when multiple identity providers are involved.
->
-> Now paste the token into the next command.
-
-**Compliant example:**
-
-> Step 4: Exchange the authorization code for a token.
->
-> Note: For why this works, see [Explanation: Authentication Flow].
-
-**Fix:** Extract all "why" content to a separate explanation document. Leave only the action and the minimum guidance needed to complete the learning exercise.
-
-## Anti-Pattern 2: How-To That Teaches
-
-**Detection signals:** "Let's learn...", "First, understand that...", explanations of basic concepts, beginner-level framing.
-
-**Failure mode:** Experienced users waste time reading fundamentals they already know.
-
-**Violation example:**
-
-> # How to Deploy
->
-> Before we deploy, let's learn what Docker is. Docker is a containerization platform that packages software with its dependencies so it can run consistently across environments. Containers differ from virtual machines because they share the host kernel...
-
-**Compliant example:**
-
-> # How to Deploy
->
-> Prerequisites: Docker installed. If you need setup help, see [Tutorial: Getting Started with Docker].
->
-> 1. Build the image.
-> 2. Push it to the registry.
-> 3. Roll out the new version.
-
-**Fix:** Assume competence. Split foundational teaching into a tutorial for learners and keep the how-to focused on completing a task for someone who already knows the basics.
-
-## Anti-Pattern 3: Reference with Narrative
-
-**Detection signals:** First-person voice ("I recommend..."), opinions, step-by-step instructions in a reference table, anecdotes.
-
-**Failure mode:** Reference becomes unreliable for quick lookup; opinions pollute facts.
-
-**Violation example:**
-
-> | Parameter | Type | Description |
-> |-----------|------|-------------|
-> | `retry` | `number` | I usually set this to `5` because it feels safer in production, and in my experience lower values make operators nervous. |
-
-**Compliant example:**
-
-> | Parameter | Type | Default | Constraints |
-> |-----------|------|---------|-------------|
-> | `retry` | `number` | `3` | Integer, `0-10` |
->
-> For recommended usage patterns, see [How-To: Retry Configuration Best Practices].
-
-**Fix:** Strip opinions into explanation content and move procedures into a how-to. Keep the reference page factual, terse, and optimized for lookup.
-
-## Anti-Pattern 4: Explanation with Procedures
-
-**Detection signals:** Numbered steps, imperative commands, "Step 1:", code blocks with instructions to run.
-
-**Failure mode:** Reader expecting understanding gets confused by action items; the document serves neither purpose well.
-
-**Violation example:**
-
-> # Why We Use Microservices
->
-> Our architecture separates services by deployment boundary and ownership model.
->
-> Step 1: Create a new service directory under `services/`.
-> Step 2: Copy the standard Dockerfile.
-> Step 3: Register the service in the gateway config.
-
-**Compliant example:**
-
-> # Why We Use Microservices
->
-> This architecture reduces coupling between release cycles, lets teams own isolated domains, and supports scaling services unevenly.
->
-> For the practical workflow, see [How-To: Create a New Service].
-
-**Fix:** Move procedures to a how-to or tutorial. Keep explanation documents discursive, interpretive, and focused on reasoning rather than execution.
-
-## Anti-Pattern 5: Mixed-Mode Document
-
-**Detection signals:** Multiple quadrant signals in one document; tutorial narration plus reference tables plus explanation prose; a page with more than two distinct purposes.
-
-**Failure mode:** The document serves no single purpose well, becomes impossible to maintain, and grows without bound.
-
-**Violation example:**
-
-> # Authentication Guide
->
-> OAuth lets users delegate access without sharing passwords. Here is a beginner-friendly walkthrough of the handshake. Below is the full endpoint matrix and token schema. Next, compare session cookies with JWTs and evaluate the security trade-offs. Finally, follow these steps to configure SSO in production.
-
-**Compliant example:**
-
-Split the material into four documents:
-
-1. Tutorial: Getting Started with Authentication
-2. Reference: Authentication API
-3. Explanation: Authentication Architecture Decisions
-4. How-To: Configure SSO
-
-**Fix:** Split the page into separate documents, one per quadrant. Cross-link them so readers can move between learning, doing, understanding, and lookup without mode-switching inside a single page.
-
-## Blur Zones
-
-Common cases where the boundary between two quadrants is genuinely ambiguous:
-
-| Content | Looks Like | Actually Is | Disambiguation |
-|---------|-----------|-------------|----------------|
-| Getting Started | Tutorial or How-to | Ask whether there is a learning journey. If yes, it is a Tutorial. If it is just "get it running", it is a How-to. | Look for staged learning versus immediate task completion. |
-| Architecture Overview | Explanation or Reference | If it explains why the system is shaped this way, it is Explanation. If it lists components, schemas, or interfaces, it is Reference. | Ask whether the page interprets or inventories. |
-| Troubleshooting | How-to or Reference | If it says "do X when Y happens", it is a How-to. If it is a lookup table of error codes or symptoms, it is Reference. | Ask whether the reader is acting or checking. |
-| Best Practices | Explanation or How-to | If it explains reasoning and trade-offs, it is Explanation. If it gives actionable steps to follow, it is a How-to. | Ask whether the content persuades or instructs. |
-| Changelog | Reference or Explanation | It is almost always Reference because it is a factual record. It only becomes Explanation when it includes design rationale and interpretation. | Ask whether the entry records changes or argues for them. |
-
-## Common Mistakes
-
-| Mistake | Why It's Wrong | Fix |
-|---------|----------------|-----|
-| Writing a tutorial that tries to be comprehensive | Tutorials should teach one thing well, not cover everything. | Narrow the scope and link to reference for completeness. |
-| Embedding opinions in reference docs | Reference must be factual and trustworthy. | Move opinions to explanation docs. |
-| Creating empty four-section structures | Diátaxis is a quality framework, not a template to fill. | Let structure emerge from actual content needs. |
-| Making how-to guides that explain everything | How-to assumes competence; explanations break flow. | Link to tutorials for prerequisites and explanations for context. |
-| Writing explanation that lacks opinion or perspective | Good explanation connects concepts and provides insight. | Take a position and explain trade-offs and reasoning. |
-| Trying to classify every page | Some pages, such as README or index pages, are navigation rather than content. | Navigation pages do not need quadrant classification. |
-
-## Attribution
-
-This reference adapts concepts from the Diátaxis framework at diataxis.fr and from keithpatton/diataxis-agent-skill. Diátaxis framework content is licensed under CC-BY-SA 4.0; retain attribution and share-alike terms for further adaptations.

package/scaffold/_preview/skills/docs/references/diataxis-compass.md

@@ -1,123 +0,0 @@
-# The Diataxis Compass
-
-The Diataxis Compass is a simple classification aid for documentation. It reduces classification to two axes so an author can decide what kind of document they are writing before structure and tone drift across quadrants.
-
-Use it when a draft feels mixed, when a request could fit more than one documentation type, or when you need a quick check before creating a new document.
-
-## The Two Axes
-
-The compass uses two independent axes:
-
-| Axis | Question | Poles | What it tells you |
-|------|----------|-------|-------------------|
-| Horizontal | Is the reader trying to do something or understand something? | Action vs Cognition | Whether the content should guide behavior or develop understanding |
-| Vertical | Is the reader learning or working? | Study vs Work | Whether the content serves acquisition or application |
-
-Interpret the axes this way:
-
-- **Action** means practical doing, following steps, executing work, or completing a task.
-- **Cognition** means understanding, context, concepts, relationships, or meaning.
-- **Study** means the reader is acquiring skill or knowledge.
-- **Work** means the reader is applying skill or knowledge to a real task.
-
-## ASCII Quadrant Diagram
-
-```text
-                     ACTION                              COGNITION
-          +--------------------------------+--------------------------------+
- STUDY    | Tutorial                       | Explanation                    |
-          | Learn by doing                 | Learn by understanding         |
-          +--------------------------------+--------------------------------+
- WORK     | How-to Guide                   | Reference                      |
-          | Accomplish a specific task     | Consult facts while working    |
-          +--------------------------------+--------------------------------+
-```
-
-## Two-Question Decision Tree
-
-Ask these questions in order:
-
-1. Is the reader trying to **DO** something or **UNDERSTAND** something?
-2. Is the reader **LEARNING** or **WORKING**?
-
-Answer matrix:
-
-| Q1 | Q2 | Result |
-|----|----|--------|
-| Action | Study | Tutorial |
-| Action | Work | How-to guide |
-| Cognition | Work | Reference |
-| Cognition | Study | Explanation |
-
-Short version:
-
-- Action + Study = **Tutorial**
-- Action + Work = **How-to guide**
-- Cognition + Work = **Reference**
-- Cognition + Study = **Explanation**
-
-## Content Type Signals
-
-Trigger phrases are not absolute rules, but they are strong signals.
-
-| Quadrant | Typical trigger phrases or patterns | What they usually indicate |
-|----------|-------------------------------------|----------------------------|
-| Tutorial | `build your first`, `getting started`, `learn`, `introduction to`, `beginner`, `walkthrough` | A guided learning path with a defined outcome |
-| How-to guide | `how to`, `configure`, `deploy`, `set up`, `integrate`, `migrate`, `troubleshoot` | A task-focused guide for a user trying to solve a real problem |
-| Reference | `API`, `parameters`, `options`, `schema`, `configuration`, `specification`, `returns` | Structured factual material consulted during work |
-| Explanation | `why`, `how it works`, `overview`, `trade-offs`, `background`, `concepts`, `design` | Material meant to increase understanding and context |
-
-Signals become more reliable when they align across title, headings, verbs, and document structure.
-
-## Confidence Calibration
-
-Use confidence to decide whether to classify, split, or rewrite.
-
-| Confidence | Interpretation | Recommended action |
-|------------|----------------|--------------------|
-| High | All signals match one quadrant | Classify directly and write fully in that mode |
-| Medium | Signals match one quadrant but the topic could span two | Classify to the dominant quadrant and cross-link the adjacent need |
-| Low | Mixed signals across quadrants | Split the document rather than forcing one label |
-
-Practical rule:
-
-- **High** means title, tone, structure, and user need all point the same way.
-- **Medium** means one quadrant clearly dominates, but a neighboring quadrant is tempting.
-- **Low** means the document is trying to teach, guide, explain, and describe at once.
-
-## Edge Cases
-
-Some common document labels are ambiguous on their face. Classify by function, not by title alone.
-
-| Content label | Recommended classification | Reasoning |
-|---------------|----------------------------|-----------|
-| README | Reference | Usually a project summary and entry point, not a discursive explanation |
-| FAQ | Split per question | Each answer may belong to a different quadrant |
-| Getting Started | Tutorial or How-to guide | Tutorial if aimed at learning; How-to if aimed at competent users getting started in work |
-| Troubleshooting | How-to guide | It is task-oriented problem solving |
-| Changelog | Reference | It is a factual record |
-| Architecture overview | Explanation | It exists to help the reader understand system design |
-| Migration guide | How-to guide | It helps the reader complete a concrete transition task |
-
-## Ambiguity Protocol
-
-When classification is uncertain:
-
-1. Default to the quadrant that serves the reader's immediate need.
-2. If it is still unclear, split the document by quadrant.
-3. If splitting is not worth the cost, classify it by the dominant quadrant and explicitly note the secondary one.
-
-Useful signs that a split is warranted:
-
-- the introduction promises learning, but the body is a task checklist
-- the document alternates between step-by-step actions and API facts
-- the writer keeps adding “why” digressions to operational instructions
-- headings naturally group into two different quadrant modes
-
-## Attribution
-
-This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the Compass and related quadrant descriptions.
-
-Source material is licensed under **CC-BY-SA 4.0**.
-
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).

package/scaffold/_preview/skills/docs/references/diataxis-quadrants.md

@@ -1,192 +0,0 @@
-# Diataxis Quadrants
-
-This reference describes the four documentation quadrants in Diataxis: Tutorial, How-to guide, Reference, and Explanation. Use it when a document has already been classified, or when you need boundary tests to decide whether content belongs in one quadrant or has drifted into another.
-
-## Tutorial
-
-### Definition
-
-A tutorial is a guided learning experience. It helps a reader acquire competence by doing something meaningful in a controlled path toward a defined outcome.
-
-### Tutorial Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Learning-oriented | A reference to consult |
-| Practical and guided | A set of independent steps |
-| Structured as a path | Complete coverage of a topic |
-| Built around a defined outcome | A free-form discussion |
-
-### Defining Characteristics
-
-- It is designed for a reader who is still learning.
-- It follows a deliberate path from start to finish.
-- It creates a successful encounter with the product or skill.
-- It limits choices so the learner can focus.
-- It optimizes for confidence, momentum, and visible progress.
-
-### Language Patterns
-
-Tutorial language is guided, concrete, and supportive. It commonly uses second person and first-person plural.
-
-- `In this tutorial, you will ...`
-- `You'll see ...`
-- `Next, we ...`
-- `Notice that ...`
-- `The output should look something like ...`
-
-The tone should reduce uncertainty, set expectations, and keep the learner on a single path.
-
-### Boundary Tests
-
-- If the steps can be done in any order, it is probably **not** a tutorial.
-- If there is no learning outcome, it is probably a **How-to guide**.
-- If the content starts listing all options and variants, it is drifting toward **Reference**.
-- If the content spends time on rationale and design history, it is drifting toward **Explanation**.
-
-## How-to Guide
-
-### Definition
-
-A how-to guide is a task-oriented document for someone trying to solve a specific problem or complete a real piece of work. It assumes the reader already has enough competence to act on concise guidance.
-
-### How-to Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Task-oriented | A lesson |
-| Practical | An explanation of concepts |
-| Focused on a specific problem | A comprehensive reference |
-| Written for application in real work | A broad introduction |
-
-### Defining Characteristics
-
-- It starts from a concrete goal or problem.
-- It is written for readers who are already doing work.
-- It emphasizes action, judgement, and usable sequence.
-- It avoids digressions into fundamentals unless strictly necessary.
-- It may branch for real-world conditions and alternatives.
-
-### Language Patterns
-
-How-to language is direct and imperative. It should sound executable.
-
-- `Configure X.`
-- `Deploy to Y.`
-- `Set up the service account.`
-- `If you need Z, do ...`
-- `To migrate safely, first ...`
-
-Good how-to writing is short, concrete, and free of conceptual detours.
-
-### Boundary Tests
-
-- If it teaches fundamentals before the task, it is drifting toward **Tutorial**.
-- If it mostly describes available options rather than choosing a path, it is drifting toward **Reference**.
-- If it answers `why` more than `what to do`, it is drifting toward **Explanation**.
-- If success depends on following a pedagogical sequence rather than solving a task, it belongs in **Tutorial**.
-
-## Reference
-
-### Definition
-
-Reference is factual documentation consulted during work. It describes the machinery, interface, structure, or behavior of the system as clearly and consistently as possible.
-
-### Reference Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Information-oriented | A guide |
-| Austere and factual | Opinionated |
-| Comprehensive within scope | Narrative |
-| Structured consistently | Selective in the style of a lesson |
-
-### Defining Characteristics
-
-- It is optimized for lookup, not for linear reading.
-- It presents facts, interfaces, constraints, and structure.
-- It uses a consistent pattern so readers can find answers quickly.
-- It aims for completeness inside a defined scope.
-- It avoids persuasion, instruction-heavy flow, and discursive context.
-
-### Language Patterns
-
-Reference language is descriptive, factual, and usually third person.
-
-- `Returns {type}.`
-- `Accepts the following parameters ...`
-- `Option values are ...`
-- `The schema contains ...`
-- `Configuration keys include ...`
-
-Warnings and constraints are fine, but they should remain factual rather than tutorial or argumentative.
-
-### Boundary Tests
-
-- If the content explains why a design exists, it belongs in **Explanation**.
-- If the content shows how to accomplish a task with the feature, it belongs in **How-to guide**.
-- If the content walks a newcomer through a first success path, it belongs in **Tutorial**.
-- If the content becomes selective and outcome-driven rather than complete and structured, it is no longer pure reference.
-
-## Explanation
-
-### Definition
-
-Explanation is understanding-oriented documentation. It connects concepts, provides rationale and background, and helps the reader build a mental model of the system or topic.
-
-### Explanation Is / Is Not
-
-| IS | IS NOT |
-|----|--------|
-| Understanding-oriented | Step-by-step instructions |
-| Discursive and connective | A lookup table |
-| Rich in context | A tutorial |
-| Concerned with reasons and implications | A terse list of facts |
-
-### Defining Characteristics
-
-- It provides context, rationale, and conceptual framing.
-- It connects details into a broader mental model.
-- It can discuss trade-offs, history, alternatives, and design intent.
-- It supports reflection more than immediate action.
-- It is bounded by topic rather than by task or API surface.
-
-### Language Patterns
-
-Explanation language is descriptive, interpretive, and often comparative.
-
-- `The reason for ...`
-- `This approach was chosen because ...`
-- `Consider the trade-off ...`
-- `Historically, the system evolved this way because ...`
-- `An X in this system is analogous to ...`
-
-It is acceptable here to surface perspective, evaluation, and multiple interpretations.
-
-### Boundary Tests
-
-- If the document has numbered operational steps, it likely belongs in **How-to guide** or **Tutorial**.
-- If it lists facts without context, it likely belongs in **Reference**.
-- If it promises a concrete outcome the reader will build, it likely belongs in **Tutorial**.
-- If it exists mainly to solve an immediate operational problem, it belongs in **How-to guide**.
-
-## Cross-Linking Rules
-
-Quadrants should cooperate rather than compete. Each document should point to adjacent documentation types when a different reader need appears.
-
-| From | Cross-link pattern |
-|------|--------------------|
-| Tutorial | `For the full API, see [Reference].` |
-| How-to guide | `To understand why, see [Explanation].` |
-| Reference | `For a guide on using this, see [How-to].` |
-| Explanation | `To get started, see [Tutorial].` |
-
-Use cross-links when content would otherwise drift into the wrong quadrant. Link instead of absorbing the adjacent material.
-
-## Attribution
-
-This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the quadrant descriptions and distinction pages.
-
-Source material is licensed under **CC-BY-SA 4.0**.
-
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).

package/scaffold/_preview/skills/docs/references/diataxis-quality.md

@@ -1,76 +0,0 @@
-# Diataxis Quality & Iteration
-
-How to assess and improve documentation quality using the Diátaxis framework.
-
-## Quality Checklist
-
-Run this checklist against every document created or updated during `_docs-sync`:
-
-### Quadrant Purity
-- [ ] Document serves exactly ONE Diátaxis quadrant
-- [ ] No mixed-mode content (tutorial narration + reference tables + explanation prose)
-- [ ] Language patterns match the quadrant (see diataxis-quadrants.md)
-- [ ] If content from another quadrant is needed, it's linked — not embedded
-
-### Structure & Completeness
-- [ ] All required template sections are present (see diataxis-templates.md)
-- [ ] No empty placeholder sections
-- [ ] Cross-references to related docs in other quadrants exist
-- [ ] `type:` frontmatter tag matches the actual content quadrant
-
-### Evidence & Accuracy
-- [ ] Claims are traceable to source files, config, or AI Kit tool output
-- [ ] Unknowns are marked `[TODO]`, not guessed
-- [ ] Team-intent items are marked `[ASK USER]`
-- [ ] No stale information (version numbers, deprecated APIs, removed features)
-
-### Audience Fit
-- [ ] Tutorial: assumes beginner, teaches one skill, shows visible results at each step
-- [ ] How-To: assumes competence, addresses specific task, no unnecessary explanation
-- [ ] Reference: factual, comprehensive, consistent structure, austere
-- [ ] Explanation: provides context, takes a position, connects concepts
-
-## Iterative Improvement Process
-
-Documentation improves incrementally. Don't try to perfect everything at once.
-
-### The Loop
-
-```
-1. Pick one document (or section, or paragraph)
-2. Classify it → which Diátaxis quadrant?
-3. Check → does it serve that quadrant well? (use checklist above)
-4. Make one improvement
-5. Repeat
-```
-
-### When to Iterate
-
-| Trigger | Action |
-|---------|--------|
-| New doc created during `_docs-sync` | Run full checklist before committing |
-| Existing doc updated | Check only the modified sections |
-| Docs audit requested | Run checklist on all docs; prioritize by staleness |
-| Content feels wrong but works | Classify first — often the issue is quadrant mixing |
-
-### Organic Growth (from diataxis.fr)
-
-- Let documentation structure emerge from content needs — don't create empty four-section structures
-- A project with no tutorials doesn't need a `tutorials/` directory
-- Add documentation types as the project actually needs them
-- Perfect is the enemy of good — a correct how-to guide is better than no documentation
-
-### Scoring (optional, for audits)
-
-Per document, count how many checklist items pass out of the total applicable items.
-
-| Score | Quality | Action |
-|-------|---------|--------|
-| 100% | Excellent | No action needed |
-| 75-99% | Good | Fix during next relevant change |
-| 50-74% | Needs work | Schedule improvement |
-| <50% | Poor | Rewrite or split immediately |
-
----
-
-*Quality framework follows the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*

package/scaffold/_preview/skills/docs/references/diataxis-templates.md

@@ -1,120 +0,0 @@
-# Diataxis Templates
-
-Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
-
-## Tutorial Template
-
-**Location**: `docs/guides/tutorials/{topic}.md`
-**Quadrant**: Tutorial (learning-oriented, practical)
-
-```markdown
----
-type: tutorial
----
-
-# Tutorial: {Title — Start with a Verb Phrase}
-
-> **What you'll build/learn**: One sentence describing the concrete outcome.
-
-## Prerequisites
-
-- {Prerequisite 1} — [install guide](link)
-- {Prerequisite 2}
-
-## Steps
-
-### 1. {First Visible Result}
-
-{Concrete action with immediate, visible output.}
-
-```bash
-{command or code}
-```
-
-> **You'll see**: {expected output — always show what success looks like}
-
-### 2. {Build on Step 1}
-
-{Next concrete action that builds on the previous result.}
-
-> **You'll see**: {expected output}
-
-### 3. {Complete the Goal}
-
-{Final action that achieves the tutorial's stated outcome.}
-
-> **You'll see**: {final result matching the "What you'll build" promise}
-
-## What You Learned
-
-{One-paragraph summary of skills acquired. No new concepts here.}
-
-## Next Steps
-
-- [How to {related task}](../guides/{topic}.md) — apply what you learned
-- [{Topic} Reference](../../reference/{topic}.md) — full API details
-- [About {concept}](../../architecture/{topic}.md) — understand the design
-```
-
-### Tutorial Rules
-
-1. **Always show results** — every step must have a "You'll see" block
-2. **Linear path only** — no branching, no optional steps, no alternatives
-3. **No explanations** — if the reader asks "why?", link to an Explanation doc
-4. **Concrete outcome** — the tutorial must produce something visible (output, file, running service)
-5. **Minimum viable scope** — teach ONE thing; link to other tutorials for more
-
-## Explanation Template
-
-**Location**: `docs/architecture/{topic}.md` or `docs/decisions/NNN-{title}.md`
-**Quadrant**: Explanation (understanding-oriented, theoretical)
-
-```markdown
----
-type: explanation
----
-
-# About {Topic}
-
-## Context
-
-{Why this topic matters. What problem or question it addresses. Set the stage.}
-
-## Background
-
-{Historical context, prior art, or constraints that shaped the current approach.}
-
-## How It Works
-
-{Discursive description — connections between components, data flow, design reasoning.}
-{NO step-by-step procedures — link to How-To guides for that.}
-
-## Design Decisions
-
-{Why this approach was chosen over alternatives.}
-{Link to ADRs where they exist: [ADR-NNN](../decisions/NNN-{title}.md)}
-
-## Trade-Offs
-
-| Gained | Sacrificed |
-|--------|-----------|
-| {benefit} | {cost} |
-
-## Related
-
-- [How to {task}](../guides/{topic}.md) — practical application
-- [{API} Reference](../reference/{topic}.md) — technical details
-- [Tutorial: {topic}](../guides/tutorials/{topic}.md) — hands-on introduction
-```
-
-### Explanation Rules
-
-1. **Take a position** — good explanation has perspective and opinion
-2. **Connect concepts** — show relationships, not isolated facts
-3. **No procedures** — if you write "Step 1:", move it to a How-To doc
-4. **Bounded scope** — explain ONE concept/decision/pattern per document
-5. **Link to evidence** — reference ADRs, code, or analysis tool output
-
----
-
-*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*