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)"
37 lines
1.5 KiB
Markdown
37 lines
1.5 KiB
Markdown
# 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.
|