a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# Documentation Instructions
|
|
|
|
## Core Principle
|
|
|
|
Every document starts with the **problem it solves** — one or two sentences.
|
|
Then a diagram if it clarifies, then content.
|
|
|
|
---
|
|
|
|
## Document Workflow
|
|
|
|
1. **Abstract** -- write problem statement + section headings (+ top-level diagram if relevant) directly into the file. Do not propose the structure in chat first.
|
|
2. **Align** -- stop after writing the abstract. The human reviews it in the file and confirms or adjusts before any section content is written.
|
|
3. **Section by section** -- write ~50 lines at a time, then stop and wait. The human decides when a section is ready and asks for the next one. Do not ask "did this go in the right direction?" or prompt the user to continue.
|
|
4. **Stay in scope** -- if something is complex or unclear, stop and ask rather than guess
|
|
5. **Review** -- when done, AI asks: "Is anything missing?" -- user decides
|
|
6. **Link check** -- after finishing, scan other docs in `docs/` for broken links or documents that should now link to this one
|
|
|
|
---
|
|
|
|
## Diagrams
|
|
|
|
**Abstract**: one top-level diagram showing the full scope.
|
|
**Sections**: add focused sub-diagrams to clarify specific parts.
|
|
|
|
Use **Mermaid** for flows, architecture, component relationships.
|
|
Use **ASCII trees** for file/folder structures.
|
|
When in doubt, include a diagram -- visuals are faster to read than text.
|
|
|
|
For contrast rules, sizing and diagram type selection: see [mermaid.instructions.md](mermaid.instructions.md)
|
|
|
|
---
|
|
|
|
## What Belongs in a Document
|
|
|
|
✅ Principles — how and why the system works
|
|
✅ Architecture — components, relationships, data flows
|
|
✅ Key decisions — why this approach over alternatives
|
|
✅ Scope boundaries — explicitly state what is out of scope and link to where it is covered
|
|
|
|
❌ Step-by-step commands — belong in README or runbooks
|
|
❌ Full code blocks — small illustrative examples only
|
|
❌ Troubleshooting — "if error X do Y" does not belong here
|
|
❌ All possible alternatives — pick the relevant ones, explain briefly when to use which
|
|
|
|
---
|
|
|
|
## When the User Corrects Something
|
|
|
|
- Fix **only** what was pointed out
|
|
- Do not explain why you got it wrong
|
|
- Do not add anything else at the same time
|
|
|
|
---
|
|
|
|
## Scope
|
|
|
|
Keep each document tightly scoped to its title.
|
|
|
|
If a topic needs deeper treatment:
|
|
- Ask: 'Should we create a separate document for X?'
|
|
- If yes: write a short intro sentence and link to the new doc
|
|
- Do not expand inline
|
|
|
|
---
|
|
|
|
## Length
|
|
|
|
- Increment: ~50 lines at a time, then check with user
|
|
- Hard limit: 500 lines
|
|
- If approaching limit: stop and ask user what to continue with
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
- Written in English
|
|
- No step-by-step commands -- those belong in README or runbooks
|
|
- No changelog entries
|
|
- No duplication between documents -- link instead
|