juanandresgs/claude-ctrl/decide

Decide: Structured Decision Configurator

Generate interactive decision configurators that transform complex trade-off analysis into explorable interfaces. Presents options as cards with visual hierarchy, automatic filtering, cascading dependencies, and live cost tracking.

When to Use /decide

Use this skill when decisions have:

• 3+ options with meaningful trade-offs
• Dollar amounts to compare
• Cascading dependencies (choice A eliminates options in choice B)
• Multiple dimensions to evaluate (cost, quality, risk)

Don't use for:

• Binary yes/no decisions → use AskUserQuestion
• Simple 2-option choices → use AskUserQuestion
• Decisions already made → just document them

Decision Sources

The skill can extract decision points from three sources:

1. Research directories — /decide .claude/research/DeepResearch_Auth_2026-02-11

• Parses provider reports (openai.md, perplexity.md, gemini.md)
• Extracts competing approaches and trade-offs
• Links to cited sources

1. MASTER_PLAN.md context — /decide plan

• Extracts decision points from "Architectural Decisions" section
• Pulls requirements from "Requirements" section
• Associates DEC-IDs with plan phases

1. Conversation context — /decide monitor purchase decision

• Analyzes recent conversation history
• Identifies options, constraints, and trade-offs discussed
• Generates from requirements stated in conversation

Implementation Phases

Phase 1: Identify Decision Source

If argument is a filesystem path:

• Check if it's a research directory (.claude/research/DeepResearch_*)
• Look for report.md, openai.md, perplexity.md, gemini.md
• Extract decision points from research findings

If argument is "plan":

• Read {project_root}/MASTER_PLAN.md
• Extract from "Architectural Decisions" section
• Map DEC-IDs to options
• Pull constraints from Requirements section

If argument is topic/question:

• Analyze recent conversation (last 5-10 messages)
• Identify options mentioned, trade-offs discussed
• Extract constraints and requirements from conversation

If no source is clear:

• Ask user: "I found these potential decision sources: [list]. Which should I use?"

Phase 2: Decompose Decisions

For each decision source, identify:

1. Steps — Sequential decision points (e.g., "Choose auth method" → "Choose database" → "Choose deployment")

• Each step has: title, subtitle, DEC-ID (if from plan), info box (optional context)
• Steps should flow logically — dependencies become filters

1. Options — Alternatives within each step

• Each option has: title, badge, price, specs (pros/cons), tags, links
• Mark recommended option (if clear from research/plan)
• Mark eliminated options (if constraints rule them out)

1. Filtering logic — Cascading constraints

• "If user picks 5K resolution, hide 4K monitors"
• "If user picks quantity=3, show triple-arm option"
• Document as filterBy (data-based) or visibleWhen (state-based)

1. Cost tracking — Live impact bar

• Price-based: monitors ($799 × quantity) + arms ($398) + cables ($30 × quantity)

1. Summary & Export — Final output

• Grid items: "Your monitor: ASUS ProArt PA27JCV", "Total cost: ~$2,795"
• Action items: setup instructions, next steps
• Export: JSON blob with DEC-IDs and selected options

Phase 3: Generate Config JSON

Write decision-config.json following the schema. The config is the single source of truth for the configurator. The build script injects it verbatim into the HTML template.

Reference the fixtures as examples:

1. Purchase decision pattern — See fixtures/monitor-setup.json:

• meta.type: "purchase"
• Price-based options with dollar amounts
• Impact bar with price × quantity math
• Buy links in summary
• Info boxes with domain-specific guidance

1. Technical decision pattern — See fixtures/tech-stack.json:

• meta.type: "technical"
• Documentation links instead of buy links
• Export enabled with DEC-IDs

Key config patterns:

• filterBy: Filter options in step B based on data field from selected option in step A

``json { "id": "monitor", "filterBy": { "dataField": "tier", "matchStep": "priority" } } `` Meaning: "Show only monitors where option.data.tier matches the selected priority option's ID"

• visibleWhen: Show/hide option based on exact state match

``json { "id": "triple-arm", "visibleWhen": { "step": "quantity", "equals": "qty-3" } } `` Meaning: "Show this arm option only when step 'quantity' has option 'qty-3' selected"

• impactBar.items: Dynamic cost calculation

``json { "label": "Monitors", "fromStep": "monitor", "multiplyByStep": "quantity" } `` Meaning: "Get price from selected monitor, multiply by quantity value"

When generating config:

1. Start from one of the fixture examples as a template
2. Replace domain-specific data (monitors → auth methods, prices → your domain)
3. Preserve the structure: meta, steps, impactBar, summary, research (if applicable)
4. Validate against schema mentally before writing

Write the config to decision-config.json in the working directory (or user-specified path).

Phase 4: Build and Serve

Run the build script with --serve to start a local server. This is required — the Confirm button POSTs decisions back to the server, which writes them to decisions.json on disk.

python3 ~/.claude/skills/decide/scripts/build.py decision-config.json --serve

CRITICAL: Run this with `run_in_background: true` so you can continue operating while the user interacts with the configurator. Set timeout: 600000 (10 minutes).

The script will:

1. Validate config
2. Build HTML with config injected
3. Start HTTP server on a random port (localhost only)
4. Open http://localhost:{port}/ in browser
5. Print Decisions will be saved to: {cwd}/decisions.json
6. Wait for the user to click Confirm
7. When Confirm is clicked, write decisions.json and print >>> DECISIONS CONFIRMED

Flags:

• --serve — start local server (primary mode, enables auto-submit)
• --open — open as file:// (fallback, clipboard-only, no auto-submit)
• --decisions-out PATH — custom path for decisions.json output

Phase 5: Report Back & Wait for Decisions

Tell the user:

Generated decision configurator — opening in browser.
Server running at http://localhost:{port}/
 
The configurator presents {N} decision steps with {M} total options.
Make your selections, then click "Confirm Decisions" — your choices will be submitted automatically.

Then wait for the user to say they're done (or check the background task for the >>> DECISIONS CONFIRMED message).

Phase 6: Read Confirmed Decisions

When the user confirms, the server writes decisions.json to disk. Read it directly.

Method 1: Read from file (primary — works with --serve)

cat decisions.json

Or use the Read tool on the decisions.json path that the server printed at startup. This is the default path — {cwd}/decisions.json unless --decisions-out was specified.

Check the background task output for the >>> DECISIONS CONFIRMED line to know when the file is ready. If the user says "done" but the file doesn't exist yet, tell them: "Please click the green 'Confirm Decisions' button in the configurator first."

Method 2: Chrome extension (if available) If browser automation tools are available (mcp__claude-in-chrome__*):

// Via javascript_tool on the configurator tab:
JSON.stringify(window.__DECISIONS__)

Method 3: User pastes from clipboard Fallback for --open (file://) mode where the server isn't running. The Confirm button copies JSON to clipboard.

Phase 7: Integrate Decisions

Once you have the decisions JSON, parse it and take concrete action. The JSON looks like:

{
  "decisions": {
    "auth-method": {
      "decId": "DEC-AUTH-001",
      "selected": "jwt-pkce",
      "title": "JWT + PKCE Flow",
      "rationale": "Stateless, scales horizontally"
    }
  },
  "timestamp": "2026-02-11T14:30:00Z"
}

Action depends on the invoking context:

7a. Invoked from Planner (most common)

Return the parsed decisions to the calling Planner agent. The Planner will:

1. Write each decision into ### Planned Decisions in MASTER_PLAN.md:

```

• DEC-AUTH-001: JWT + PKCE Flow — Stateless, scales horizontally — Addresses: REQ-P0-001

```

1. Populate phase **Decision IDs:** fields with the confirmed DEC-IDs
2. Continue to Phase 3 (Issue Decomposition) with user-validated decisions

To enable this, output the decisions as a structured block the Planner can parse:

CONFIRMED DECISIONS:
- DEC-AUTH-001 (auth-method): JWT + PKCE Flow — "Stateless, scales horizontally"
- DEC-DATA-001 (database): PostgreSQL + Prisma — "Type-safe queries with Prisma Client"
- DEC-DEPLOY-001 (deployment): Docker + Fly.io — "Full control over runtime environment"
SOURCE: configurator confirmed at {timestamp}

7b. Invoked standalone

Present the decisions and take the next step:

1. Show what was chosen — summarize each decision with DEC-ID, selection, and rationale
2. If MASTER_PLAN.md exists — offer to update it:

• Read the existing plan
• Find the ### Planned Decisions sections
• Replace or append the confirmed decisions using the DEC-ID as the key
• Write the updated plan

1. If no plan exists — offer to:

• Create a new MASTER_PLAN.md with these decisions as the Architectural Decisions section
• Start implementation directly based on the choices

1. If this was a purchase decision — compile the buy list with links and totals from the selected options

7c. Invoked for purchase decisions (no plan context)

For purchase decisions (meta.type = "purchase"), skip plan integration. Instead:

1. Present the final shopping list with prices and buy links
2. Offer: "Want me to open the buy links in your browser?"
3. Save the decisions to {cwd}/decisions.json for reference

Always end with forward motion — never leave decisions hanging without a next action.

Refinement workflow: If the user wants to adjust after confirming:

1. User requests change: "Add a fourth option" or "change the auth recommendation"
2. Read and update decision-config.json
3. Re-run python3 ~/.claude/skills/decide/scripts/build.py decision-config.json --output configurator.html --open
4. User re-confirms in the refreshed configurator
5. Re-read decisions (Phase 6) and re-integrate (Phase 7)

Config JSON Schema Reference

The schema is defined in schema/decision-config.schema.json. Key fields:

meta (required)

• title (string, required) — Configurator title
• subtitle (string, optional) — Subtitle/description
• type (enum, required) — "purchase" | "technical" | "implementation" | "configuration"
• Controls theme color (indigo/purple/teal/blue)
• researchDir (string, optional) — Path to research directory
• planContext (object, optional) — { masterPlan, phase, requirements[] }

steps[] (required, min 1)

• id (string, required) — Unique step identifier
• title (string, required) — Step title
• subtitle (string, optional) — Step subtitle
• decId (string, optional) — DEC-ID from MASTER_PLAN.md
• filterBy (object, optional) — { dataField, matchStep }
• infoBox (object, optional) — { html, variant: "default" | "critical" | "warning" }
• options[] (array, required, min 1) — Options for this step