--- name: write-decision-ready-technical-reports description: Turn technical investigations, plans, audits, and status updates into clear decision-ready reports without losing evidence. Use when asked to "make this plan decision-ready", "write a technical status report", "show the before and after", or clarify what is true now, what changed, what decision is needed, what each option costs, or what work remains. license: Apache-2.0 --- # Write Decision-Ready Technical Reports Make a technical report easy to skim, verify, and act on. Preserve detailed evidence, but put a small decision layer before it. A cold reader should be able to identify the current state, recommended action, alternatives, consequences, and unresolved evidence without reconstructing the investigation. ## P0 requirements 1. **REPORT-REQ001-lead-with-reader-outcome.** State the artifact's purpose, audience, current status, scope, evidence date or revision, and decisions needed in the first screen. 2. **REPORT-REQ002-separate-now-history-target.** Never mix the reproduced past, verified current state, and selected target. Use explicit `Before`, `Now`, and `Target` labels. 3. **REPORT-REQ003-separate-cause-consequence.** Put the technical mechanism and user-visible consequence in different columns. Keep each cell to one claim. 4. **REPORT-REQ004-label-evidence-state.** Use a small stable vocabulary such as `observed`, `reproduced`, `confirmed`, `selected`, `implemented`, `verified`, `blocked`, `deferred`, `rejected`, and `superseded`. Do not use “fixed” for code that has not passed its completion gate. 5. **REPORT-REQ005-make-decisions-answerable.** Phrase each decision as a concrete question and include the recommendation, serious alternatives, consequence of each choice, evidence needed, and present decision status. 6. **REPORT-REQ006-name-baselines-and-versions.** Identify the relevant commit, package, schema, running process, configuration, dataset, workload, or date. State when source, install, and live process differ. 7. **REPORT-REQ007-preserve-evidence-by-link.** Keep reproductions, logs, calculations, and design rationale in a detailed evidence section or companion artifact. Add an overview; do not replace evidence with a lossy summary. 8. **REPORT-REQ008-distinguish-artifact-roles.** Say whether a file is an evidence log, decision brief, implementation plan, status report, benchmark report, or handoff. Do not let one file silently act as all six. 9. **REPORT-REQ009-show-before-after-contract.** For proposed work, show current behavior, target behavior, user consequence, compatibility or migration effect, and completion proof. 10. **REPORT-REQ010-quantify-with-context.** Give every important number a counted thing, unit, baseline, environment or workload, and evidence source. Distinguish measurements from requirements and hypotheses. 11. **REPORT-REQ011-progressively-disclose-detail.** Order content as decision dashboard, current truth, options, execution map, then detailed evidence. Introduce terms before using them. 12. **REPORT-REQ012-preserve-complexity-tradeoffs.** State relevant time, peak and retained memory, I/O, latency, concurrency, and output-growth effects when a decision can change them. 13. **REPORT-REQ013-separate-input-from-instruction.** Distinguish information that should change the report's conclusions from information used to author, execute, or evaluate the reporting method. 14. **REPORT-REQ014-end-with-decidable-next-step.** End the decision layer with the exact choice, approval, experiment, or implementation gate needed next. ## 1. Classify the artifact Choose one primary job: | Artifact | Reader's question | Required center | | --- | --- | --- | | Evidence log | What happened, and how do we know? | Reproduction, environment, observations, ruled-out causes | | Decision brief | What should we choose? | Options, recommendation, consequences, evidence | | Implementation plan | How will the selected outcome be delivered? | Dependencies, tests, work packages, done conditions | | Status report | What is true now, and what changed? | Baseline, current state, deltas, blockers | | Benchmark report | What changed under the same workload? | Before/after measurements, uncertainty, resource effects | | Handoff | What must the next maintainer know or do? | Current truth, exact state, risks, first action | If one file must serve several jobs, label the sections and declare which section has current authority. ## 2. Build the decision dashboard Start with these compact tables, omitting only rows that do not apply. | Field | Answer | | --- | --- | | Purpose | One sentence | | Current status | One precise state | | Evidence baseline | Date, revision, environment, or workload | | In scope | Bounded surfaces or components | | Out of scope | Nearby work not authorized or not selected | | Decision needed | Exact answerable question, or `none` | Then show the smallest useful state transition: | Area | Before or reproduced issue | Now | Target | User consequence | | --- | --- | --- | --- | --- | | One capability | Prior behavior | Verified current behavior | Selected behavior | Why the difference matters | Do not repeat the same facts in both tables. ## 3. Make decisions explicit Use one row per independent choice: | ID | Decision question | Recommendation | Serious alternative | Consequence | Status or closing evidence | | --- | --- | --- | --- | --- | --- | | DEC-1 | A concrete question | Selected mechanism | Keep current or another viable design | User and system effect | Ready, blocked, or evidence required | Separate a prerequisite experiment from the decision it informs. If no decision remains, say so and identify the implementation gate instead. ## 4. Map execution without hiding tradeoffs For each accepted work package, use: - **Where:** authoritative owner and affected adapters. - **Current:** verified behavior, not stale plan text. - **Target:** exact externally visible and internal contract. - **Why:** user consequence and architectural rationale. - **Tests first:** smallest failing reproduction and cross-surface regressions. - **Complexity:** present and target time, memory, I/O, latency, concurrency, and output bounds. - **Compatibility:** migration, versioning, default, and rollback effects. - **Done when:** observable completion gate. - **Dependencies:** prior decisions, work packages, or external action. ## 5. Streamline and verify 1. Remove repeated conclusions while retaining unique evidence. 2. Split cause from consequence and current state from interpretation. 3. Keep tables narrow; move multi-paragraph reasoning below the table. 4. Use bold sparingly for the user-visible impact or selected choice. 5. Check every status word against its proof. 6. Ask a cold reader to answer: What is true now? What changes? Why? What can I decide? What remains uncertain? Where is the proof? 7. If any answer requires scanning the detailed evidence, repair the dashboard. Deliver a report whose first section is sufficient to make the named decision and whose later sections are sufficient to audit it. Include: - a document contract and evidence baseline; - a `Before / Now / Target / consequence` view; - an explicit decision register or the statement `No decision remains`; - an implementation or verification map; - links to preserved evidence; - precise next action. Do not present a roadmap as current status, a hypothesis as a defect, implementation as verification, a shortened view as complete evidence, or a large table as a substitute for a decision.