Decision Brief

---
name: decision-brief
description: >
  Package extracted findings into a compact, decision-ready format for engineers, managers, or
  review bodies. Use this after running complexity-mapper, architecture-risk-review, or
  context-sharding to synthesize findings into a structured brief with options, evidence, risks,
  and recommended next steps. Produces a Decision Brief with evidence summary, top risks,
  unresolved questions, and actionable recommendations. Ask for a "decision brief",
  "decision package", or "summarize findings for a decision" to use this workflow.
---

In Codex, first read the [native runtime adapter](../../references/codex-runtime.md).


# Decision Brief

## When to Use

Use Decision Brief when:

- Findings from extraction, analysis, or prior workflow runs need to be packaged for a specific decision audience — engineering leads, architecture review boards, management, or cross-functional stakeholders.
- A decision is pending and the decision-makers need a structured, evidence-based summary rather than raw analysis output.
- You need to translate technical findings into a format that supports clear reasoning about options, trade-offs, and next steps.
- Multiple prior workflows have produced outputs that need to be synthesized into a single coherent recommendation surface.

Do **not** use Decision Brief when:

- No extraction or analysis has been performed yet. Run `complexity-mapper`, `context-sharding`, or `architecture-risk-review` first to generate the raw findings.
- The decision is purely technical and the audience is the same person who did the analysis. In that case, the raw analysis output may be sufficient.
- The findings are too preliminary for a decision — flag this and recommend further analysis instead of producing a weak brief.

## Inputs Required

| Input              | Required | Description                                                                                                                                                                      |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Extracted findings | Yes      | Outputs from prior workflow runs: Context Packets, Complexity Heat Maps, Hidden Risk Summaries, or direct analysis results. The more structured the input, the better the brief. |
| Ranked risks       | Yes      | Prioritized list of risks with severity assessments. Typically produced by complexity-mapper or architecture-risk-review. If not available, the brief will flag this gap.        |
| Assumptions        | Yes      | Assumptions underlying the findings — both validated and unvalidated. These become critical context for decision-makers.                                                         |
| Decision audience  | No       | Who will read this brief and what decisions they are empowered to make. Shapes the level of technical detail and the framing of options. Defaults to technical leadership.       |
| Options considered | No       | If multiple design or implementation options were evaluated, provide them. If not provided, the brief will present findings as applying to the current proposed approach.        |

## Process Steps

### Step 1: Gather Extraction Outputs

Collect all available outputs from prior workflow runs or direct input:

- Context Packets from `context-sharding`
- Complexity Heat Maps and Hidden Risk Summaries from `complexity-mapper`
- Risk assessments from `architecture-risk-review`
- Pattern Remix Drafts from `pattern-remix`
- Source Manifests from `web-researcher` (if web research was performed upstream)
- Dispatch Plans from `extraction-planner` (for understanding how extraction was parallelized)
- Any direct analysis notes, findings, or data provided by the user

For each input, verify:

1. **Source anchors are present**: Every finding should trace back to specific evidence. Unanchored findings get flagged as inferred.
2. **Confidence ratings are present**: If the input doesn't include confidence, assign conservative ratings and note that they were not part of the original analysis.
3. **Recency**: Ensure the findings are current. Stale analysis based on outdated documentation should be flagged.

If the inputs are insufficient for a meaningful brief — fewer than three substantive findings, no risk assessment, or no concrete evidence — **stop and recommend** running `complexity-mapper` or another appropriate upstream workflow first. Do not produce a thin brief that creates false confidence.

### Step 2: Invoke synthesis-brief-writer with Decision Brief Contract

Before final synthesis, check `../../reference/examples/` for sample Decision Brief outputs. Match the format and depth of any found examples to maintain consistency. Also check `../../reference/prompts/` for decision-framing patterns the user has found effective — these can sharpen the brief's structure and language.

Pass all gathered inputs to the `synthesis-brief-writer` agent with the Decision Brief output contract and the following instructions:

**Structure the brief to answer these questions in order:**

1. **What is being decided?** Frame the decision clearly. If the user hasn't stated the decision explicitly, infer it from the findings and flag the inference.
2. **What options were considered?** List each option with a one-sentence description. If only one option was analyzed, state this and note that the brief reflects a single-option assessment.
3. **What does the evidence say?** Summarize findings organized by option. Separate evidence-backed findings from inferred concerns. Every finding must cite its source.
4. **What are the top risks?** Present the highest-severity risks with their triggers, impact, and likelihood. Include source anchors.
5. **What is unresolved?** List open questions that the decision-makers should be aware of — things the analysis could not answer, data that was missing, assumptions that remain unvalidated.
6. **What should happen next?** Recommend concrete next steps: validations to run, prototypes to build, vendor conversations to have, follow-up analyses to commission.

**Synthesis-brief-writer constraints:**

- Do not introduce new analysis. The brief synthesizes existing findings; it does not generate new ones.
- Mark every inferred concern with `[Inferred]` so decision-makers can distinguish evidence from interpretation.
- If findings from different sources contradict each other, present both perspectives. Do not silently resolve contradictions.
- Keep the brief under 2 pages of content (excluding tables). Decision-makers will not read longer documents; move supporting detail to appendices.

### Step 3: Verify Output Completeness

Before presenting, check the Decision Brief against these requirements:

- [ ] **Decision frame**: The decision being made is clearly stated.
- [ ] **Options considered**: At least one option is described. Single-option briefs are explicitly labeled as such.
- [ ] **Evidence summary**: Findings are organized, sourced, and confidence-rated.
- [ ] **Inferred concerns marked**: Every inference is labeled `[Inferred]`.
- [ ] **Top risks**: At least three risks are listed with severity, trigger, and source. If fewer than three risks were identified, flag this as unusual.
- [ ] **Unresolved questions**: At least one open question is listed. If none were found, flag this — it usually means the analysis wasn't deep enough.
- [ ] **Recommended next steps**: Concrete, actionable items with rationale.
- [ ] **Length check**: Core brief fits in 2 pages. Appendices are used for supporting detail.

If any check fails, return to the `synthesis-brief-writer` with specific feedback.

### Step 4: Present to User

Deliver the Decision Brief with:

- A one-line summary of the decision and the brief's top recommendation (or "no recommendation — insufficient evidence" if that is the case).
- The full brief.
- A note on what would strengthen the brief if the user wants higher confidence: additional data, further analysis, stakeholder input.

## Output Format

The output is a **Decision Brief** conforming to the output contract:

```
## Decision Brief

### Decision Frame
[What is being decided, who is deciding, and what authority level is required]

### Options Considered
| Option | Description | Analysis Depth |
|---|---|---|
| [Option A] | [One-sentence description] | [Full / Partial / Surface-level] |
| [Option B] | [One-sentence description] | [Full / Partial / Surface-level] |

### Evidence Summary

#### Option A
- [Finding]: [Source] — Confidence: [H/M/L]
- [Finding]: [Source] — Confidence: [H/M/L]
- [Inferred] [Concern]: [Reasoning] — Confidence: [L]

#### Option B
- [Finding]: [Source] — Confidence: [H/M/L]

### Top Risks
| Risk | Severity | Trigger | Evidence Source | Confidence |
|---|---|---|---|---|
| [Risk] | [Critical/High/Medium] | [What causes it] | [Source anchor] | [H/M/L] |

### Contradictions (if any)
- [Source A] says [X]; [Source B] says [Y]. Resolution requires: [action].

### Unresolved Questions
| Question | Why It Matters | Suggested Resolution |
|---|---|---|
| [Question] | [Impact on decision] | [How to answer it] |

### Recommended Next Steps
1. [Action]: [Rationale] — Owner: [Suggested]
2. [Action]: [Rationale] — Owner: [Suggested]

### Appendices (if needed)
- [Appendix A: Full risk inventory]
- [Appendix B: Detailed evidence tables]
```

## Failure Modes and Caution Points

| Failure Mode                        | Signal                                                                                                  | Response                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Insufficient extraction data        | Step 1 yields fewer than 3 substantive findings or no risk assessment                                   | Stop. Do not produce a thin brief. Recommend running `complexity-mapper` or `architecture-risk-review` first to generate adequate raw material.                                                  |
| Single-perspective input            | All findings come from one source, one extraction agent, or one analysis workflow                       | Flag in the brief that the evidence base is limited. Lower all confidence ratings by one level. Recommend additional analysis from a different angle.                                            |
| Missing cost or dependency analysis | No findings related to cost implications or system dependencies                                         | Flag the gap explicitly in the Unresolved Questions section. Recommend running the relevant extraction (cost-capacity-analyst or architecture-dependency-mapper) before finalizing the decision. |
| Stale findings                      | Input findings are based on documentation or analysis more than 30 days old                             | Flag recency concerns in the brief. Recommend re-running upstream analysis with current documentation before making the decision.                                                                |
| False precision                     | Brief presents low-confidence findings as high-confidence, or uses precise numbers from rough estimates | Review confidence ratings in Step 3. Ensure `[Inferred]` labels are applied. Remove false precision from quantitative claims.                                                                    |
| Scope creep in synthesis            | synthesis-brief-writer introduces new analysis not present in the inputs                                | Reject and re-invoke. The brief synthesizes; it does not analyze. New observations must be labeled `[Inferred]` at minimum, but the brief should not be the place for new investigation.         |