@vpxa/aikit 0.1.65 → 0.1.67

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

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

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