1.7 KiB
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>/<title>.md
Examples:
tmp/symlink-vs-copy/comparison.mdtmp/curl-installer/design.mdtmp/harness-options/analysis.md
TOPIC is a short slug describing the subject area. <title>.md describes what the document contains. Use lowercase and hyphens.
CRITICAL RULE: Do NOT create analysis files or any temporary files in the project root. Always use the tmp/<topic>/ folder structure.
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.