@vpxa/aikit 0.1.73 → 0.1.75

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

@@ -1,553 +0,0 @@
----
-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.
-```
-
-### Decision Index Template (`docs/decisions/index.md`)
-
-```markdown
-# Architecture Decision Record Index
-
-This page is the ADR log for the project. IDs are assigned sequentially as decisions are recorded.
-
-## Index
-
-| ID | Title | Status | Date | Source |
-| --- | --- | --- | --- | --- |
-| ADR-001 | {Decision title} | {Accepted/Proposed/Deprecated/Superseded} | {YYYY-MM-DD} | [{flow-topic}]({relative-path-to-flow-artifact}) |
-```
-
-The **Source** column links to the flow artifact (typically `design.md` or `design-decisions.md`) where the decision was originally designed. Use the flow's run directory path relative to the index file location (e.g., `../../.flows/{topic}/{artifacts}/design.md`). If the decision was made outside a flow, use "Manual" or link to the relevant discussion.
-
-### 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`
-- Include the Source column linking to the flow artifact where the decision was designed.
-- 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
-
-### Mermaid Syntax Rules
-
-When generating Mermaid diagrams in documentation:
-
-- **Quote node labels containing special characters** — Names with `@`, `/`, or other special characters must be wrapped in double quotes inside square brackets: `subgraph Commons["@scope/package-name"]`, `NodeId["@org/lib"]`
-- **Quote subgraph titles with special characters** — `subgraph Title["@scope/name"]` not `subgraph @scope/name`
-- Node IDs (aliases) must not contain special characters — use plain alphanumeric IDs and put the display name in `["..."]`
-
-## 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 with Source column linking to flow artifacts
-├── 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
-
-## Link Rules
-
-### Relative Path Correctness
-
-All links in generated docs must be correct relative to the file that contains them. Compute the path from the target doc's directory, not from the project root.
-
-| Doc location | Link to `src/types/index.ts` | Link to `.flows/topic/artifacts/design.md` |
-|---|---|---|
-| `docs/README.md` | `../src/types/index.ts` | `../.flows/topic/artifacts/design.md` |
-| `docs/architecture/overview.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
-| `docs/decisions/index.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
-| `docs/reference/api.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
-
-**Rules:**
-1. Count the directory depth from the doc file to `docs/`, then add `../` to reach the project root
-2. Verify every link target exists before writing it — use `find({ pattern })` if unsure
-3. Never use absolute paths in documentation — always relative
-4. Test links mentally: from `docs/architecture/overview.md`, `../../` reaches the project root
-
-## 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/).*