stress-test

Stress Test: Adversarial Design Interrogation

<!-- Inspired by mattpocock/skills grilling (MIT). Attribution: README "Built on". -->

Announce at start: "I'm using the stress-test skill to interrogate this design."

Purpose

Stress-test a design, plan, or decision by walking down every branch of the decision tree. For each question, provide your own recommended answer — don't just ask, propose. This forces the user to either agree explicitly or articulate why their approach is better.

This is NOT brainstorming (which creates designs) or verification (which checks implementations). This is the gap between them: "Is this design actually solid before we commit to building it?"

When to Invoke

| Trigger | Context | |---------|---------| | After brainstorming | Stress-test the design spec before writing a plan | | After writing-plans | Stress-test the plan before execution begins | | User says "grill me" | On-demand for any document, decision, or approach | | Before a major architectural decision | Ensure alternatives were genuinely considered |

The Process

# Create a stress-test bead
bd create "Stress-test: <topic>" -t chore -p 2 \
  --description="Adversarial review of <artifact>. Branches to interrogate: <count>"
bd update <id> --claim

Phase 1: Understand the Target

Read the design, plan, or decision document thoroughly. If no document exists, ask the user to describe the approach. Explore the codebase for context — answer your own questions from code when possible rather than asking the user.

Restore point (Mode A only): If the target artifact has uncommitted changes, commit or stash them before starting — this preserves a clean restore point before inline edits begin. In the normal flow (brainstorming → stress-test), the artifact is already committed.

Done when: the target is understood well enough to enumerate its decision branches, and (Mode A) the artifact sits at a clean restore point.

Phase 2: Map the Decision Tree

Identify every decision branch in the target:

• Architecture choices (why X over Y?)
• Assumptions (what breaks if this is wrong?)
• Dependencies (what happens if this changes?)
• Edge cases (what about when Z happens?)
• Scale (does this work at 10x? 100x?)
• Failure modes (what's the worst case?)
• Alternatives not considered (what about approach W?)
• Security & risk (mandatory branch): does any branch take a shortcut, descope a requirement, or accept material risk? Does anything weaken or bypass a security control, or introduce a vulnerability? Per the Production-Grade Doctrine, a design that does fails the stress test by default. (If the design has no security surface, resolve this branch as "no security surface — N/A" — do not fabricate a finding.)

Done when: every branch category above has been checked against the target, including the mandatory Security & risk branch.

Phase 3: Interrogate One Branch at a Time

For each branch, present your question and recommendation as text, then use your structured question tool for the response.

Per-branch flow:

1. Present the question + recommendation as text in the message body (reasoning needs room to breathe)
2. Immediately follow with a structured question (content below; shape shown in Claude Code schema — adapt to your tool):

{
  "questions": [{
    "question": "<1-sentence summary of the branch being interrogated>",
    "header": "Stress test",
    "options": [
      {"label": "Agree", "description": "Accept the recommendation and move to the next branch"},
      {"label": "Disagree", "description": "I have a different view — let me explain"},
      {"label": "Discuss further", "description": "I want to explore this branch more before deciding"}
    ],
    "multiSelect": false
  }]
}

Response handling:

• Agree — Mark branch resolved, emit status line, advance to next branch
• Disagree — Ask "What's your alternative?" as text (open-ended — disagreements need space). Iterate until the branch resolves, then re-ask the same 3-option structured question on the revised position.
• Discuss further — Explore deeper (code, docs, implications), present updated analysis, then re-ask the same structured question

Branch tracking: After each branch resolves, emit a status line:

✓ Resolved: 3/7 branches (2 agreed, 1 modified)
Remaining: Error handling, Scale, Rollback, Testing strategy

Rules:

• One branch at a time — never batch. Wait for the user's response on each branch before presenting the next; surfacing several at once is bewildering and dilutes the recommendation each one deserves.
• Always state your recommendation in the message body BEFORE the structured question — the recommendation is the substance; the click is just the gate
• If you can answer by exploring the codebase, do that instead of asking
• When the user agrees, move on. When they push back, explore deeper.

Done when: every mapped branch is marked resolved and the status line reads N/N.

Phase 4: Document Findings

After all branches are resolved, write the findings. The output mode depends on context.

Mode detection:

• Mode A applies when: the stress-test was invoked by brainstorming or writing-plans (caller passes the artifact path), OR the user explicitly points at a .internal/specs/ or .internal/plans/ file.
• Mode B applies for everything else: user-initiated "grill me" with no artifact, stress-testing a conversation or decision, or targeting documents that shouldn't be edited inline (README, CLAUDE.md, etc.).
• When ambiguous: Use your structured question tool to ask:

{
  "questions": [{
    "question": "I see `<file>`. Should I edit it inline with findings, or produce a separate stress-test report?",
    "header": "Output mode",
    "options": [
      {"label": "Edit inline (Mode A)", "description": "Apply changes directly to the source document and append a results summary"},
      {"label": "Separate report (Mode B)", "description": "Write findings to .internal/stress-tests/ without modifying the source"}
    ],
    "multiSelect": false
  }]
}

Mode A — Existing artifact (spec, plan, design doc in .internal/):

• Edit the source artifact directly when a branch changes the design.
• At the end, append a ## Stress Test Results section at the bottom of the source document:

## Stress Test Results: <topic>

### Resolved Decisions
- [Decision 1]: [Resolution and rationale]
- [Decision 2]: [Resolution and rationale]

### Changes Made
- [Any modifications to the original design/plan]

### Deferred / Parking Lot
- [Items explicitly deferred for later]

### Confidence Assessment
- Overall: High/Medium/Low
- Areas of concern: [Any remaining worries]

Alternatively, record as a bd note on the parent bead if the source doc shouldn't be modified further.

Mode B — Standalone stress test (no existing artifact):

• Create .internal/stress-tests/YYYY-MM-DD-<topic>.md with the full findings template above.
• Open in user's editor for review:

User's preferred editor: !echo ${VISUAL:-${EDITOR:-not-configured}}

# Open in user's preferred editor, with platform fallbacks
if [ -n "$VISUAL" ]; then
  "$VISUAL" "<findings-file-path>"
elif [ -n "$EDITOR" ]; then
  "$EDITOR" "<findings-file-path>"
elif command -v open >/dev/null 2>&1; then
  open "<findings-file-path>"
else
  xdg-open "<findings-file-path>" 2>/dev/null
fi
# If none available: just report the path

Done when: findings exist in the applicable form — Mode A's Results section appended (or a bd note recorded), or Mode B's report file created.

Phase 4.5: Reflexion Self-Review

After documenting findings, run a single self-critique pass. This is internal reasoning — not shown to the user. Only the consequences (new or re-opened branches) are visible.

Self-critique questions:

1. Coverage: Compare branches mapped in Phase 2 against branches actually i