| name | decision-packet-builder |
| description | Bundles unresolved choices into ADR/RFC-style decision packets with options, trade-offs, and recommendations. Trigger — "build a decision packet", "write an ADR", "document this decision", "what are our options for X". Skip when the decision is trivial or already made. |
| license | Apache-2.0 |
| compatibility | {"clients":["openai-codex","gemini-cli","opencode","github-copilot"]} |
| metadata | {"owner":"codex","domain":"decision-packet-builder","maturity":"draft","risk":"low","tags":["decision","packet","builder"]} |
Purpose
Collects all pending major decisions into a single structured packet so they can be reviewed, debated, and resolved in one pass rather than as a stream of interruptions. This follows the Architecture Decision Record (ADR) pattern: each decision is documented with context, options, consequences, and a recommendation, creating a durable record of why choices were made.
When to use this skill
Use when:
- The user says "what decisions do we need to make?", "build a decision packet", "batch the open questions", or "prepare decisions for review"
- A project is stalled because multiple unresolved choices are blocking each other
- A stakeholder review is upcoming and decisions need to be prepared with context
- Planning is producing more questions than answers and they need organization
- Multiple people need to align on choices before work proceeds
Do NOT use when:
- Only one decision needs to be made (just make a recommendation directly)
- The decisions are already resolved and need implementation
- The user wants tradeoff analysis for a single option comparison (use
tradeoff-analysis)
- The user wants risks identified (use
premortem)
Operating procedure
-
Identify all open decisions: Scan the plan, conversation, or document for:
- Explicit questions ("Should we use X or Y?")
- "TBD" markers
- Forks in the approach
- Options mentioned but not chosen
- Unstated choices that must be made before implementation
-
Filter for major decisions: Only include decisions that:
- Block other work if unresolved
- Are hard to reverse once made
- Have meaningful tradeoffs between options
- Require stakeholder input or alignment
-
Group by dependency: Identify which decisions block others. Order them: decisions that must be made first appear first.
-
For each decision, write a structured ADR-style entry:
- Decision ID: Short label (D1, D2, etc.)
- Question: One clear sentence stating what must be decided
- Context: Why this matters, what happens downstream, what triggered this decision point
- Options: 2-4 concrete options, each with a one-sentence description
- Tradeoffs: For each option, the key upside and downside (one sentence each)
- Recommendation: The option you recommend and why, stated directly—do not hedge
- Reversibility: Easy / Moderate / Hard to change later
- Deadline: When this must be decided to avoid blocking progress
-
Summarize the decision graph: Show which decisions depend on which, using notation like "D2 depends on D1".
-
Flag irreversible decisions: Mark any choice that would be very costly to undo with ⚠️ HIGH STAKES.
Output defaults
A structured Decision Packet document with:
- Header: project name, date, author
- One entry per decision using the template above
- A Decision Dependencies section showing the order
- A Immediate Attention Required section for decisions blocking 2+ others
Example format per decision:
## D1: Database selection
**Question**: Which database should we use for user data storage?
**Context**: This choice affects data model design, query patterns, and operational complexity. Must be decided before schema design begins.
**Options**:
1. PostgreSQL — Mature, relational, strong consistency
2. MongoDB — Document store, flexible schema, eventual consistency
3. DynamoDB — Managed, serverless, pay-per-request
**Tradeoffs**:
| Option | Upside | Downside |
|------------|----------------------------------|---------------------------------|
| PostgreSQL | Team expertise, ACID guarantees | Self-managed, scaling overhead |
| MongoDB | Schema flexibility | Less team experience |
| DynamoDB | Zero ops, auto-scaling | Vendor lock-in, query limits |
**Recommendation**: PostgreSQL. Team has 5+ years of experience, and the use case fits relational patterns. Scaling concerns are premature optimization.
**Reversibility**: Hard — data migration required
**Deadline**: Before sprint 2 planning (March 10)
Named failure modes of this method
- Decision inflation: Including trivial or easily reversible choices alongside genuinely major decisions, diluting attention. Fix: apply the filter in step 2 strictly—only include decisions that block work, are hard to reverse, or require alignment.
- Option theater: Listing options without genuine tradeoff analysis, making the "recommended" option look like the only reasonable choice. Fix: every option must have at least one genuine upside, or it shouldn't be listed.
- Missing the meta-decision: Packaging decisions for review without identifying which decision must be made first, causing the reviewer to stall on dependencies. Fix: always produce the dependency graph (step 5).
- Recommendation hedging: Saying "it depends" or "both are valid" instead of making a clear recommendation. Fix: always recommend one option directly. If you genuinely cannot decide, name the specific experiment or information that would break the tie.
- Stale packets: Building a decision packet that sits unreviewed. Fix: every packet must include a deadline for each decision and a named reviewer/decision-maker.
References
Failure handling
If insufficient context exists to produce Options or Tradeoffs for a decision:
- Mark that decision as Needs More Context
- List specifically what information is required
- Include the decision in the packet but flag it as incomplete
- Proceed with other decisions that can be fully analyzed
