moilanik a6eb4da214 nit: ai-superpower initial commit

- .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)"

2026-03-02 14:06:36 +02:00

2.7 KiB

Raw Blame History

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

Abstract -- write problem statement + section headings (+ top-level diagram if relevant) directly into the file. Do not propose the structure in chat first.
Align -- stop after writing the abstract. The human reviews it in the file and confirms or adjusts before any section content is written.
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.
Stay in scope -- if something is complex or unclear, stop and ask rather than guess
Review -- when done, AI asks: "Is anything missing?" -- user decides
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

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

2.7 KiB Raw Blame History