668d1e007f
- enforce strict isolation of scratch work into categorized subfolders to prevent pollution of the project root and temporary root - prohibit obfuscating Helm resource names behind complex logic functions to prioritize readability in internal deployment manifests
39 lines
1.7 KiB
Markdown
39 lines
1.7 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>/<title>.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. `<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.
|