# 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.