Design Rationale Investigation
Establish what is known about a design decision and what remains inference.
Workflow
- Define the exact decision, time window, system boundary, and question the answer will inform.
- Inspect current code and tests to establish mechanics before investigating history.
- Prefer direct evidence: decision records, commit history, linked issues, review discussions, release notes, incident records, and named documentation.
- Search only authorized sources relevant to the named decision. Ask before reading private chat, broad activity history, or unrelated repositories.
- Build competing hypotheses and test each against dates, changes, constraints, rejected alternatives, and later corrections.
- Classify every conclusion as
Direct evidence, Strong inference, Weak hypothesis, Contradiction, or Unknown.
- Recheck the current system before recommending action because historical reasons may no longer apply.
Done when
The investigation is done when each conclusion is classified and its implication for the current decision is stated. Stop and ask before widening the search beyond the authorized sources.
Boundaries
- Do not treat commit order, code comments, or repeated claims as proof of intent by themselves.
- Do not enumerate every available tool, data source, or conversation by default.
- Do not spawn agents or access external systems without host and user authority.
- Do not rewrite history or implementation as part of the investigation.
Output
Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.
Return Current mechanics, Timeline, Evidence, Hypotheses, Contradictions, Confidence, Expired assumptions, and Decision implications.
Example
Synthetic example; not an observed client result.
Input: A comment says the cache avoids a slow legacy query; no decision record exists.
Output: The comment supports that rationale, but its current relevance is unverified. Compare the query and history before treating the cache as necessary or obsolete.
1---2name: investigate-design-rationale3description: "Investigates why a design exists when asked why code was written that way or which constraint drove it; distinguishes historical evidence from plausible explanations."4license: MIT5metadata:6 source: https://skillmd.com/skills/jovanipink/investigate-design-rationale7 author: "Measured Studios"8 version: "0.19.0"9 plugin: "measured-workflows"10 invocation: "implicit"11 provenance: "original"12 risk_class: "network-read"13---1415# Design Rationale Investigation1617Establish what is known about a design decision and what remains inference.1819## Workflow20211. Define the exact decision, time window, system boundary, and question the answer will inform.222. Inspect current code and tests to establish mechanics before investigating history.233. Prefer direct evidence: decision records, commit history, linked issues, review discussions, release notes, incident records, and named documentation.244. Search only authorized sources relevant to the named decision. Ask before reading private chat, broad activity history, or unrelated repositories.255. Build competing hypotheses and test each against dates, changes, constraints, rejected alternatives, and later corrections.266. Classify every conclusion as `Direct evidence`, `Strong inference`, `Weak hypothesis`, `Contradiction`, or `Unknown`.277. Recheck the current system before recommending action because historical reasons may no longer apply.2829## Done when3031The investigation is done when each conclusion is classified and its implication for the current decision is stated. Stop and ask before widening the search beyond the authorized sources.3233## Boundaries3435- Do not treat commit order, code comments, or repeated claims as proof of intent by themselves.36- Do not enumerate every available tool, data source, or conversation by default.37- Do not spawn agents or access external systems without host and user authority.38- Do not rewrite history or implementation as part of the investigation.3940## Output4142Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.4344Return `Current mechanics`, `Timeline`, `Evidence`, `Hypotheses`, `Contradictions`, `Confidence`, `Expired assumptions`, and `Decision implications`.4546## Example4748Synthetic example; not an observed client result.4950Input: A comment says the cache avoids a slow legacy query; no decision record exists.5152Output: The comment supports that rationale, but its current relevance is unverified. Compare the query and history before treating the cache as necessary or obsolete.