@vpxa/aikit 0.1.63 → 0.1.65

package/scaffold/general/skills/docs/SKILL.md

@@ -0,0 +1,509 @@
+---
+name: docs
+description: "Living documentation management — Diátaxis framework, docs/ convention, create/update rules, staleness detection, integration with adr-skill and c4-architecture."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [code-changes, flow-artifacts, architecture]
+  outputs: [documentation]
+  relatedSkills: [adr-skill, c4-architecture]
+  internal: true
+---
+
+# Docs — Living Documentation Skill
+
+Manage the `docs/` folder as a single source of truth for project documentation. This skill runs during the mandatory `_docs-sync` epilogue step of every flow, ensuring documentation stays in sync with code changes.
+
+## Principles
+
+1. **Living, not legacy** — Documentation is updated as code changes, never as a separate "docs sprint"
+2. **One source of truth** — Never duplicate what's in code comments, READMEs, or inline JSDoc
+3. **Diátaxis framework** — Organize docs into four categories using the two-question compass:
+  - **Q1**: Is the reader trying to **do** something (action) or **understand** something (cognition)?
+  - **Q2**: Is the reader **learning** (study) or **working** (work)?
+  - Action+Study → Tutorial · Action+Work → How-to · Cognition+Work → Reference · Cognition+Study → Explanation
+  - See [references/diataxis-compass.md](references/diataxis-compass.md) for the full classification system
+4. **Minimal but complete** — Create docs only when they add value beyond what code communicates
+5. **Delegate to specialists** — Architecture diagrams → `c4-architecture` skill. Decision records → `adr-skill`
+
+## Documentation Modes
+
+This skill operates in two modes, often combined:
+
+### Source-Only Mode
+Generate documentation from code analysis alone. Used when:
+- Bootstrapping `docs/` for the first time (`produce_knowledge`, `analyze_*` tools)
+- Running outside a flow context (manual documentation refresh)
+- Flow produced no artifacts (auto-skipped design step)
+
+### Flow-Aware Mode (Primary)
+Generate documentation from code changes **plus** flow artifacts. This is the primary mode during `_docs-sync` because every completed flow produces structured artifacts containing design decisions, requirements, and verification results.
+
+Flow artifacts are the most valuable documentation input — they capture the *why* behind changes (decisions, constraints, trade-offs, risks) while code only shows the *what*.
+
+**Artifact reading sequence:**
+```
+flow_status()                                      # Get artifactsPath
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all artifacts
+digest({ sources: [                                # Compress into working context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+See [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md) for the artifact catalog and artifact-to-documentation mapping.
+
+## AI Kit Tools for Documentation
+
+Use these existing AI Kit tools to generate documentation content — never write docs from scratch when a tool can provide the foundation:
+
+| Documentation Task | AI Kit Tool | What It Provides |
+|---|---|---|
+| Project overview | `produce_knowledge({ path: "." })` | Comprehensive analysis: structure, patterns, dependencies → `docs/README.md` |
+| Architecture overview | `analyze_structure({ path: "." })` | File tree, package layout, layer organization → `docs/architecture/overview.md` |
+| Architecture diagrams | `analyze_diagram({ path: "." })` | Mermaid diagrams of component relationships → `docs/architecture/` |
+| Dependency map | `analyze_dependencies({ path: "." })` | Import graph, cross-package edges → `docs/architecture/overview.md` dependencies section |
+| Component analysis | `analyze_symbols({ path: "src/component" })` | Exports, classes, interfaces → `docs/architecture/components/{name}.md` |
+| Entry points / API surface | `analyze_entry_points({ path: "." })` | CLI bins, route handlers, main exports → `docs/reference/api.md` |
+| Code patterns | `analyze_patterns({ path: "." })` | Design patterns, conventions → `docs/architecture/overview.md` patterns section |
+| Impact analysis | `blast_radius({ changed_files: [...] })` | What's affected by changes → targeted doc updates |
+| Change detection | `git_context({})` | Recent changes, diff summary → determine which docs need updating |
+| Module graph | `graph({ action: 'neighbors', node_id })` | Who-imports-whom, cross-package dependencies → architecture diagrams |
+| Full audit | `audit({ path: "." })` | Structure + deps + patterns + health + dead symbols → comprehensive docs refresh |
+
+### Tool-First Workflow
+
+When creating documentation, always start with tool output, then enhance with human context:
+
+```
+1. Run the relevant analysis tool(s)
+2. Use the output as the doc's foundation
+3. Add: purpose/motivation (why, not just what)
+4. Add: decision context (link to ADRs)
+5. Add: cross-references to related docs
+6. Remove: implementation details visible in code
+```
+
+## `docs/` Convention
+
+```
+docs/
+├── README.md                      ← Project overview + docs index (always exists)
+├── architecture/
+│   ├── overview.md                ← C4 context + container diagrams (c4-architecture skill)
+│   ├── stack.md                   ← Language, runtime, frameworks, all dependencies
+│   ├── structure.md               ← Directory layout, entry points, key files
+│   ├── design.md                  ← Layers, patterns, data flow
+│   ├── conventions.md             ← Naming, formatting, error handling, imports
+│   ├── integrations.md            ← External APIs, databases, auth, monitoring
+│   ├── testing.md                 ← Frameworks, file organization, mocking strategy
+│   ├── concerns.md                ← Tech debt, bugs, security risks, perf bottlenecks
+│   └── components/
+│       └── {component-name}.md    ← Per-component technical docs
+├── decisions/                     ← Architecture Decision Records (adr-skill)
+│   ├── index.md                   ← ADR log / table of contents
+│   └── NNN-{title}.md             ← Individual ADRs
+├── guides/
+│   ├── tutorials/                 ← Learning-oriented lessons (Diátaxis: Tutorial)
+│   │   └── {topic}.md
+│   └── {topic}.md                 ← How-to guides for common tasks (Diátaxis: How-To)
+└── reference/
+    ├── api.md                     ← API reference (endpoints, schemas, auth)
+    └── configuration.md           ← Configuration options and environment variables
+```
+
+### Directory Purposes
+
+| Directory | Diátaxis Quadrant | What Goes Here | When to Create/Update |
+|-----------|-------------------|----------------|----------------------|
+| `architecture/` | Explanation + Reference | C4 diagrams, project knowledge (stack, structure, design, conventions, integrations, testing, concerns), component docs | Initial onboarding, new component, structural change, architecture decision |
+| `decisions/` | Explanation | ADRs — why decisions were made | Non-trivial technical decision (see adr-skill triggers) |
+| `guides/` | How-To | Step-by-step instructions for tasks | New workflow, complex setup, common operations |
+| `guides/tutorials/` | Tutorial | Learning-oriented guided lessons with concrete outcomes | New technology/feature adoption, onboarding new developers |
+| `reference/` | Reference | API docs, config options, data schemas | API change, new config option, schema modification |
+
+## Change-to-Doc Mapping
+
+Use this decision tree to determine what documentation action to take after a flow completes:
+
+```
+What changed?
+├── New component/module/package
+│   ├── Creates public API? → Create docs/architecture/components/{name}.md + update reference/api.md
+│   └── Internal only? → Update docs/architecture/overview.md (component list)
+├── API change (new endpoint, changed contract, new config)
+│   └── Update docs/reference/api.md or docs/reference/configuration.md
+├── Architecture/infrastructure decision
+│   └── Delegate to adr-skill → creates/updates docs/decisions/NNN-{title}.md
+├── Structural/architecture change
+│   └── Delegate to c4-architecture skill → updates docs/architecture/overview.md
+├── New developer workflow (build, deploy, test pattern)
+│   └── Create or update docs/guides/{topic}.md
+├── Bug fix
+│   ├── Reveals missing docs? → Create the missing doc
+│   └── Straightforward fix? → No docs update needed
+└── Dependency update / refactor / cleanup
+    └── No docs update needed (unless public API changed)
+```
+
+### Classify by Diátaxis Quadrant
+
+After determining the documentation action, classify the target document's quadrant:
+
+| Action → Cognition? | Study → Work? | Quadrant | Target Directory |
+|---------------------|---------------|----------|------------------|
+| Action (doing) | Study (learning) | **Tutorial** | `guides/tutorials/` |
+| Action (doing) | Work (applying) | **How-To** | `guides/` |
+| Cognition (understanding) | Work (using) | **Reference** | `reference/` |
+| Cognition (understanding) | Study (grasping) | **Explanation** | `architecture/`, `decisions/` |
+
+Use the [Diátaxis Compass](references/diataxis-compass.md) for edge cases and ambiguous content.
+
+## Templates
+
+### Component Doc Template (`docs/architecture/components/{name}.md`)
+
+```markdown
+# {Component Name}
+
+## Purpose
+One-paragraph description of what this component does and why it exists.
+
+## Architecture
+- **Location**: `src/{path}/`
+- **Entry point**: `{file}`
+- **Key dependencies**: {list}
+
+## Public API
+Brief description of the component's public interface.
+
+## Design Decisions
+- Link to relevant ADRs: [ADR-NNN](../../decisions/NNN-{title}.md)
+
+## Data Flow
+How data enters, transforms through, and exits this component.
+```
+
+### Guide Template (`docs/guides/{topic}.md`)
+
+```markdown
+# How to {Task}
+
+## Prerequisites
+What you need before starting.
+
+## Steps
+1. Step one
+2. Step two
+3. Step three
+
+## Verification
+How to confirm it worked.
+
+## Troubleshooting
+Common issues and solutions.
+```
+
+### Reference Template (`docs/reference/{topic}.md`)
+
+```markdown
+# {Topic} Reference
+
+## Overview
+Brief description of what this reference covers.
+
+## {Section}
+
+| Item | Type | Default | Description |
+|------|------|---------|-------------|
+| ... | ... | ... | ... |
+```
+
+> **Tutorial and Explanation templates**: For the remaining two Diátaxis quadrants, see [references/diataxis-templates.md](references/diataxis-templates.md).
+
+## Integration with Other Skills
+
+### `adr-skill` Integration
+- All ADRs live in `docs/decisions/`
+- When the docs-sync step detects an architecture decision was made during the flow, delegate to `adr-skill`
+- After `adr-skill` creates/updates an ADR, update `docs/decisions/index.md`
+- Cross-reference ADRs from component docs where relevant
+
+### `c4-architecture` Integration
+- Architecture diagrams live in `docs/architecture/`
+- When the docs-sync step detects structural changes (new packages, changed boundaries), delegate to `c4-architecture`
+- Use Mermaid format for docs files (not HTML) — markdown renders in GitHub
+- Reference diagrams from component docs
+
+## Project Knowledge Acquisition
+
+Produces seven populated documents in `docs/architecture/` covering everything needed to work effectively on the project — stack, structure, design, conventions, integrations, testing, and concerns.
+
+**Only document what is verifiable from files or tool output — never infer or assume.**
+
+### Output Contract
+
+All of the following must be true before finishing:
+
+1. All seven files exist in `docs/architecture/`: `stack.md`, `structure.md`, `design.md`, `conventions.md`, `integrations.md`, `testing.md`, `concerns.md`
+2. Every claim is traceable to source files, config, or AI Kit tool output
+3. Unknowns are marked `[TODO]`; intent-dependent decisions are marked `[ASK USER]`
+4. Every document includes a short "Evidence" section with file paths or tool receipts
+5. Final response includes numbered `[ASK USER]` questions and intent-vs-reality divergences
+
+### Documents
+
+| Document | Covers | Primary Tools |
+|----------|--------|---------------|
+| `stack.md` | Language, runtime, frameworks, dependencies, dev tooling | `analyze_dependencies`, `analyze_structure` |
+| `structure.md` | Directory layout, entry points, key files, packages | `analyze_structure`, `analyze_entry_points` |
+| `design.md` | Layers, patterns, data flow, component boundaries | `analyze_structure`, `analyze_patterns`, `analyze_diagram` |
+| `conventions.md` | Naming, formatting, error handling, import conventions | `analyze_patterns`, `search("conventions")` |
+| `integrations.md` | External APIs, databases, auth, monitoring, CI/CD | `analyze_dependencies`, `search("API\|database\|auth")` |
+| `testing.md` | Test frameworks, file organization, mocking, coverage | `analyze_patterns`, `test_run({})`, `search("test")` |
+| `concerns.md` | Tech debt, bugs, security risks, perf, high-churn files | `audit()`, `dead_symbols()`, `git_context()` |
+
+Use [references/project-knowledge-templates.md](references/project-knowledge-templates.md) for the standard template of each document.
+
+### Workflow & References
+
+Follow the four-phase workflow: **Scan → Investigate → Populate → Validate**.
+
+- [references/project-knowledge-workflow.md](references/project-knowledge-workflow.md) — Full 4-phase workflow, investigation tools per document, population rules, focus area mode
+- [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) — Environment gotchas and anti-pattern table
+
+## Architecture Blueprint Generation
+
+When bootstrapping `docs/` for the first time or refreshing architecture documentation, generate a comprehensive architecture blueprint. This replaces manual documentation with tool-driven analysis.
+
+### Blueprint Workflow
+
+```
+Step 1: Detect & Analyze
+  analyze_structure({ path: "." })                    → project layout, packages, layers
+  analyze_patterns({ path: "." })                     → conventions, design patterns
+  analyze_entry_points({ path: "." })                 → API surface, CLI entry points
+
+Step 2: Map Dependencies
+  analyze_dependencies({ path: "." })                 → import graph, cross-package edges
+  graph({ action: 'find_nodes', name_pattern: '*' })   → module graph nodes
+  graph({ action: 'neighbors', node_id: '...' })       → dependency directions
+
+Step 3: Visualize
+  analyze_diagram({ path: "." })                      → Mermaid architecture diagrams
+  Delegate to c4-architecture skill                    → C4 context/container/component views
+
+Step 4: Synthesize
+  produce_knowledge({ path: "." })                    → comprehensive analysis
+  Combine outputs into docs/ structure
+```
+
+### Blueprint Sections
+
+The architecture blueprint should cover these areas (adapted from the Architecture Blueprint Generator pattern):
+
+#### 1. Architecture Detection & Analysis
+- **Auto-detect**: Project type, framework, architectural pattern (Clean Architecture, Microservices, Layered, etc.)
+- **Tools**: `analyze_structure` → folder organization, `analyze_patterns` → framework detection, `analyze_dependencies` → dependency flow
+- **Output**: `docs/architecture/overview.md` header section
+
+#### 2. Architectural Overview
+- Guiding principles from code structure
+- Architectural boundaries and enforcement mechanisms
+- Hybrid patterns or adaptations
+- **Tools**: `produce_knowledge` + `analyze_structure`
+- **Output**: `docs/architecture/overview.md` main body
+
+#### 3. Architecture Visualization
+- High-level subsystem diagram
+- Component interaction diagrams
+- Data flow diagrams
+- **Tools**: `analyze_diagram` + `c4-architecture` skill
+- **Output**: `docs/architecture/overview.md` diagrams + `docs/architecture/diagrams/`
+
+#### 4. Core Architectural Components
+For each major component:
+- Purpose and responsibility
+- Internal structure
+- Key abstractions
+- Interaction patterns
+- **Tools**: `analyze_symbols({ path: "component/" })` + `compact({ path, query: "exports" })`
+- **Output**: `docs/architecture/components/{name}.md`
+
+#### 5. Layers & Dependencies
+- Layer structure as implemented
+- Dependency rules between layers
+- Abstraction mechanisms for separation
+- Circular dependencies or violations
+- **Tools**: `analyze_dependencies` + `graph({ action: 'neighbors' })`
+- **Output**: `docs/architecture/overview.md` layers section
+
+#### 6. Cross-Cutting Concerns
+Document implementation patterns for:
+- Error handling & resilience
+- Logging & observability
+- Validation patterns
+- Configuration management
+- **Tools**: `analyze_patterns` + `search({ query: "error handling" })`
+- **Output**: `docs/architecture/overview.md` cross-cutting section
+
+#### 7. Testing Architecture
+- Test framework and strategy
+- Test boundary patterns (unit, integration, e2e)
+- Test file conventions
+- **Tools**: `analyze_patterns` + `search({ query: "test" })`
+- **Output**: `docs/guides/testing.md`
+
+#### 8. Extension & Evolution
+- How to add features while preserving architecture
+- Component creation patterns
+- Integration patterns for external systems
+- **Tools**: `analyze_entry_points` + `analyze_patterns`
+- **Output**: `docs/guides/contributing.md` or `docs/architecture/overview.md` extension section
+
+## Rules for the `_docs-sync` Epilogue Step
+
+When this skill is loaded during the `_docs-sync` epilogue:
+
+### 0. Gather Flow Artifacts
+
+Read all available artifacts from the completed flow before assessing code changes:
+
+```
+flow_status()                                      # Get artifactsPath, topic, phase
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover all flow artifacts
+digest({ sources: [                                # Compress artifacts for context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Map each discovered artifact to documentation actions using [references/flow-artifacts-guide.md](references/flow-artifacts-guide.md).
+
+Read every artifact `find()` returns — different flows produce different files. Focus on artifacts that contain decisions, requirements, and verification results; skip artifacts that only repeat completed work.
+
+If `flow_status()` returns no active flow or no artifacts directory exists, skip this step (source-only mode).
+
+### 1. Assess Changes (tool-driven)
+
+```
+git_context({})                                    # What changed in this flow
+blast_radius({ changed_files: ["changed-files"] }) # Impact analysis
+```
+
+Use the output to classify changes against the Change-to-Doc Mapping decision tree.
+
+### 1b. Classify Target Quadrant
+
+For each doc action identified in Step 1, determine the Diátaxis quadrant:
+
+1. Ask: **Action or Cognition?** Is the reader doing something or understanding something?
+2. Ask: **Study or Work?** Is the reader learning or applying?
+3. Match the answer pair to a quadrant → pick the target directory
+4. If ambiguous → consult [references/diataxis-compass.md](references/diataxis-compass.md) for edge cases
+
+Run the [quality checklist](references/diataxis-quality.md) against any doc created or substantially modified.
+
+### 2. Apply the Mapping
+
+Follow the Change-to-Doc Mapping decision tree above to determine required documentation actions.
+
+### 3. Bootstrap `docs/` If Needed (tool-driven)
+
+If `docs/` doesn't exist, run the full Architecture Blueprint workflow:
+
+```
+# Generate content with tools
+produce_knowledge({ path: "." })           # → docs/README.md foundation
+analyze_structure({ path: "." })           # → docs/architecture/overview.md structure section
+analyze_diagram({ path: "." })             # → docs/architecture/ Mermaid diagrams
+analyze_dependencies({ path: "." })        # → docs/architecture/overview.md dependency section
+analyze_entry_points({ path: "." })        # → docs/reference/api.md foundation
+analyze_patterns({ path: "." })            # → docs/architecture/overview.md patterns section
+
+# Create the docs/ tree
+docs/
+├── README.md              ← From produce_knowledge output + project context
+├── architecture/
+│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
+│   └── components/        ← From analyze_symbols per major component
+├── decisions/
+│   └── index.md           ← ADR log (delegate to adr-skill)
+├── guides/
+│   └── testing.md         ← From analyze_patterns test info
+└── reference/
+    └── api.md             ← From analyze_entry_points
+```
+
+### 4. Update Existing Docs (tool-assisted)
+
+- Use `compact({ path: "docs/existing.md", query: "section to update" })` to read the current section
+- Use `blast_radius` output to identify which sections need updating
+- **Don't rewrite** — update relevant sections, preserve existing content
+- **Don't duplicate** — reference code comments/READMEs instead of copying
+
+### 5. Delegate When Appropriate
+
+- Architecture decisions → `adr-skill` → `docs/decisions/`
+- Architecture diagrams → `c4-architecture` skill → `docs/architecture/`
+- Blueprint refresh → Run Blueprint Workflow above
+
+### 6. Update the Index
+
+If docs were added/removed, update `docs/README.md` index.
+
+### 7. Skip If Nothing Changed
+
+If the flow's changes don't warrant doc updates (e.g., pure bug fix with no revelations), report "No documentation updates needed" and move on.
+
+## Writing Style
+
+Follow these rules when generating documentation content. Adapted from *The Elements of Agent Style* (CC BY 4.0, Yue Zhao) and classic writing authorities.
+
+### Clarity and Precision
+- **Concrete over abstract** — Use specific terms, not vague language ("the retry handler" not "the relevant component")
+- **No needless words** — Cut filler; every sentence earns its place
+- **Active voice when the agent matters** — "The scheduler retries failed jobs" not "Failed jobs are retried"
+- **Affirmative form** — State what something does, not what it does not do (unless a warning)
+- **Claims match evidence** — Do not overstate or understate; back factual claims with file paths or tool output
+
+### Structure
+- **Parallel structure** — Express coordinate ideas in similar form (consistent table columns, consistent list grammar)
+- **Stress position** — Place the important information at the end of the sentence
+- **Sentence variety** — Break sentences over 30 words; vary length to maintain rhythm
+- **Bullets only for genuine lists** — Do not convert flowing prose into bullet points; two items or a sentence do not need bullets
+
+### AI-Tell Avoidance
+- **No dying metaphors** — Avoid "cutting-edge", "leverages", "streamlines", "robust", "seamless"
+- **No transition-word openers** — Do not start paragraphs with "Additionally", "Furthermore", "Moreover"
+- **No em-dash overuse** — Use commas, semicolons, or separate sentences instead
+- **No summary closers** — Do not end every paragraph by restating what it just said
+- **Consistent terminology** — Pick one term and use it throughout; do not alternate synonyms for variety
+
+## Anti-Patterns
+
+### Documentation Maintenance
+- ❌ Documenting implementation details that are obvious from code
+- ❌ Creating docs for every small change (use the mapping tree)
+- ❌ Duplicating information already in code comments or README files
+- ❌ Writing docs that will be immediately outdated (e.g., exact version numbers)
+- ❌ Creating empty placeholder docs "for later"
+- ❌ Rewriting existing docs from scratch instead of updating sections
+
+### Quadrant Mixing (Diátaxis)
+- ❌ **Tutorial with Explanation** — conceptual paragraphs between steps → extract "why" to Explanation doc, link from tutorial
+- ❌ **How-To that Teaches** — "Let's learn..." framing in a task guide → assume competence, link prerequisites
+- ❌ **Reference with Narrative** — opinions in API tables ("I recommend...") → strip opinions to Explanation doc
+- ❌ **Explanation with Procedures** — numbered steps in a conceptual doc → move procedures to How-To
+- ❌ **Mixed-Mode Document** — one doc serving multiple quadrants → split into separate documents per quadrant
+- See [references/diataxis-anti-patterns.md](references/diataxis-anti-patterns.md) for detection signals, counterexamples, and blur zones
+
+### Project Knowledge
+- See [references/project-knowledge-gotchas.md](references/project-knowledge-gotchas.md) for environment gotchas and anti-pattern table
+
+---
+
+*Diátaxis content in this skill and its reference files is adapted from the [Diátaxis framework](https://diataxis.fr/) by Daniele Procida, used under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).*

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

@@ -0,0 +1,147 @@
+# 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.