challenge

Plan Challenger

Challenge the current implementation plan to find defects, risks, and improvement opportunities: $ARGUMENTS

Steps

0. Enter plan mode

If not already in plan mode, call the EnterPlanMode tool before doing anything else. This ensures the correct model is used and prevents accidental code changes during the challenge.

0.5. Read language configuration

Read the language to use for all generated files:

! cat .aidocs/config.yaml 2>/dev/null || cat .aidocs/config.yml 2>/dev/null || echo "language: en"

Extract the language field (default: en if neither file exists or the field is absent). All content written to .aidocs/ must be in this language.

1. Locate the active plan

Read the current plan file. The path is always in the system-reminder at the top of the conversation (/Users/cjuega/.claude/plans/<plan-name>.md). If no plan file is mentioned or found, ask the user to provide the path.

2. Challenge the plan

Analyze the plan across these dimensions (focus on $ARGUMENTS areas first if provided):

• Correctness & completeness: Does the plan actually solve the stated problem? Are there gaps or missing steps?
• Scalability & performance: Will this approach hold under load? Any N+1 queries, missing indexes, unbounded operations?
• Security: OWASP top 10, injection, authentication/authorization gaps, secrets handling, input validation
• Maintainability & coupling: Tight coupling, violation of existing patterns, hidden dependencies, dead code paths introduced
• Testability: Can the changes be tested in isolation? Are there missing test cases or untestable designs?
• Backwards compatibility & migrations: Breaking changes to APIs or DB schemas? Rollback strategy?
• Error handling & edge cases: What happens on failure? Are all error paths handled? Race conditions?
• Operational concerns: Observability (logging, metrics, tracing), deployment order dependencies, feature flags needed?

3. Classify each finding

Assign one of four severity levels:

Severity	When to use
CRITICAL	The plan has a bug, security vulnerability, data loss risk, or fundamentally cannot achieve its goal
SEVERE	Significant scalability issue, design that will create major tech debt, missing backwards compatibility, no rollback strategy
MODERATE	Recommended design improvements, uncovered edge cases, testing gaps, minor performance concerns
MINOR	Naming inconsistencies, style, optional improvements, low-impact suggestions

4. Present findings to the user

Format the report as:

## Challenge Report — Iteration N

### CRITICAL (X findings)
**[C1] <Short title>**
- **Problem**: What is wrong
- **Impact**: What will break or go wrong
- **Suggestion**: How to fix it in the plan

### SEVERE (X findings)
**[S1] <Short title>**
- **Problem**: ...
- **Impact**: ...
- **Suggestion**: ...

### MODERATE (X findings)
**[M1] <Short title>**
- **Problem**: ...
- **Suggestion**: ...

### MINOR (X findings)
**[L1] <Short title>**
- **Suggestion**: ...

---
Summary: X critical, X severe, X moderate, X minor

5. Interactive loop

If there are CRITICAL or SEVERE findings:

Ask the user which ones to resolve. Present them as a numbered list and let the user choose (can be all, some, or none). For each finding the user wants to resolve:

1. Propose the specific plan changes needed to address it
2. Wait for user approval of the proposed changes
3. Apply the approved changes to the plan file
4. After all selected findings are applied, re-run the challenge from step 2 (increment iteration counter)

If only MODERATE and MINOR findings remain (or the user chooses not to resolve any CRITICAL/SEVERE):

Ask the user if they want to resolve any of the remaining findings, or if they are comfortable proceeding. If they want to resolve some, follow the same process above.

When the user is satisfied or says to stop iterating:

Proceed to step 6.

6. Persist unresolved findings

After the user is done iterating, collect all findings that were not resolved in the plan.

1. Check if .aidocs/plan-findings/ directory exists:

   ! ls .aidocs/plan-findings/ 2>/dev/null || echo "No findings yet"

2. Determine the filename using today's date and a kebab-case slug from the plan title:

   • Format: YYYYMMDD-<plan-slug>.md
   • Example: 20260403-migrate-auth-to-jwt.md

3. Only create the file if there are unresolved findings. Write it using the template below.

4. Present the findings file path to the user.

Findings File Template

# Plan Challenge: <Plan Title>

- **Date**: YYYY-MM-DD
- **Plan**: <path to plan file>
- **Iterations**: <number of challenge iterations performed>
- **Status**: Open

## Resolved in plan

<brief list of findings that were resolved during the challenge session>

## Unresolved findings

### [SEVERITY] <Finding title>

- **Severity**: Critical | Severe | Moderate | Minor
- **Description**: What problem was detected
- **Impact**: What could happen if left unresolved
- **Suggestion**: How to resolve it
- **Decision**: Why it was left unresolved (user's rationale, if provided)

Only include findings that were not resolved in the plan. Do not include findings the user resolved.

Guidelines

• Be adversarial but constructive — the goal is to strengthen the plan, not block progress
• Focus on problems in the plan itself, not general good practices unrelated to the proposed changes
• Tailor the challenge depth to the plan's scope — a one-line fix needs less scrutiny than an architecture change
• When proposing plan changes, be specific: reference exact sections, steps, or wording to modify
• Keep iteration counter visible across iterations so the user knows how many rounds have been done
• If no active plan is found in the conversation context, say so clearly and ask the user to provide the plan content or file path