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

1.5 KiB

Raw Blame History

Analysis Instructions

Analysis documents are scratch work — comparisons, evaluations, investigations. They live in tmp/ which is gitignored. They are never docs/.

Where to write

tmp/<TOPIC>/filename.md

Examples:

tmp/symlink-vs-copy/comparison.md
tmp/curl-installer/design.md
tmp/harness-options/analysis.md

TOPIC is a short slug describing the subject area. filename describes what the document contains. Use lowercase and hyphens.

Scope

Analysis is strictly scoped to the question asked. Do not expand into adjacent decisions unless the user asks. The purpose is to inform a decision, not to redesign the system.

Writing style

Analysis documents are the exception to the section-by-section documentation workflow. Write the full document in one pass. The user reads it as a whole and decides what to do next.

Structure to use when relevant:

Context — what problem or question this addresses
Options — what the alternatives are, with concrete tradeoffs per option
Recommendation — what to do and why (be direct, no hedging)
Open questions — what still needs a decision, if anything

Not all sections are required. A short comparison with a clear recommendation may need only a table and a conclusion.

What analysis is not

Analysis documents do not become documentation. If a decision is made based on an analysis, the decision gets documented in docs/architecture.md or the relevant doc file. The analysis in tmp/ stays as scratch — it is not cleaned up, updated, or committed.

1.5 KiB Raw Blame History