@vpxa/aikit 0.1.65 → 0.1.67

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

@@ -1,147 +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
-
+# 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/general/skills/docs/references/diataxis-compass.md

@@ -1,123 +1,123 @@
-# 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**.
-
+# 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/).