Mine Challenge

Challenge

Adversarial review of any artifact — code, specs, designs, briefs, skill files. Assumes the target is wrong and sets out to prove it. A Haiku triage pass selects 1–3 critics best suited to the target; critics run in parallel and findings are synthesized, classified, and executed inline.

Arguments

$ARGUMENTS — optional scope:

• File/path: /mine-challenge src/services/user_service.py
• Module/concept: /mine-challenge "the auth module"
• Empty: brief recon to find the most suspect design areas, then confirm scope

Optional arguments (extracted from the beginning of $ARGUMENTS only — stop at first non-flag token):

• --focus="<area>" — steer critics; also forces any specialist whose filename slug prefix-matches (≥6 chars, case-insensitive, single word only)
• --target-type=<type> — override heuristic classification. Values: code, frontend-code, spec, design-doc, brief, skill-file, agent-file, rule, docs, research, other
• --mode=passthrough — present summary only; skip inline resolution (mine-brainstorm, mine-research)
• --no-specialists — triage selects from generic personas only
• --critics=N — pin the critic count to exactly N, clamped to the number of eligible personas (12 total: 3 generic, 9 specialist — fewer if --no-specialists is also set). Overrides triage's default 1–3 range and the re-challenge cap of 2. When --focus forces a specialist, that specialist occupies one of the N slots rather than adding to them.
• --re-challenge — mark this run as a re-challenge. Replaces the file-based detection.

How to Analyze

Do NOT run tests, execute builds, or write throwaway scripts.

DO use Read, Grep, Glob, git log/git diff. Use WebSearch to cite canonical patterns or failure modes.

Finding Taxonomy

Every finding gets: severity (CRITICAL / HIGH / MEDIUM / TENSION), type (Structural / Approach-now / Approach-later / Fragility / Gap), design-level (Yes / No), classification (Auto-apply / User-directed).

See ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/findings-protocol.md for classification criteria, visibility/disposition fields, and the inline resolution flow.

Phase 1: Triage

Parse arguments and create tmpdir

Extract flags from $ARGUMENTS. Run get-skill-tmpdir mine-challenge — note the directory (e.g., /tmp/claude-mine-challenge-a8Kx3Q). All intermediate files live here.

Read target and classify type

Determine the input shape and read the target:

• File path: read the file(s) fully
• List file (.txt/.list): read as newline-separated paths; skip blank/comment lines; record missing files to <tmpdir>/validation-warnings.md
• Inline content (multi-sentence markdown): treat as target text directly

Classify target type — use --target-type if provided, otherwise:

design-doc terminal-status caveat: if the target's **Status:** is archived or abandoned, note it here for Phase 2 — the dispatch bullet list there tells critics not to flag drift from current code as a finding.

Re-challenge detection

Check for a prior challenge run before dispatching triage:

1. If --re-challenge flag was provided → re-challenge.
2. Fallback: if conversation context shows a prior challenge against this target → re-challenge.

Note re-challenge status in context for Phase 2 critic selection.

Dispatch Haiku triage subagent

Dispatch a single triage subagent (subagent_type: light-worker). Pass:

• Full target content (or file paths to read)
• Target type classification
• Re-challenge flag (yes / no)
• --focus value if provided
• --no-specialists flag if provided
• --critics=N value if provided
• The persona catalog (name + one-line description from each frontmatter):

Generics:

• senior-engineer.md — Skeptical Senior Engineer: runtime risks, edge cases, security, operational blindness
• systems-architect.md — Systems Architect: abstraction violations, change amplification, data model problems
• adversarial-reviewer.md — Adversarial Reviewer: wrong solution entirely, UX failures, "should this exist?"

Specialists:

• agent-definition.md — Agent Definition Critic: agent file quality, executor compatibility, scope leakage
• contract-caller.md — Contract & Caller Critic: output schema fragility, breaking change surface, implicit contracts
• data-integrity.md — Data Integrity Critic: transaction safety, partial writes, cache/source-of-truth divergence
• documentation-architect.md — Documentation Architect Critic: doc set structure, mode confusion, findability gaps
• end-user-reader.md — End-User Reader Critic: assumed prerequisites, missing steps, error path silence
• operational-resilience.md — Operational Resilience Critic: resource exhaustion, upstream failures, recovery behavior
• structural-minimalist.md — Structural Minimalist Critic: speculative layers, single-consumer abstractions, bolted-on requirements, designs that could be half the size
• web-platform.md — Web Platform Critic: re-renders, data fetching patterns, accessibility, CSS architecture
• workflow-ux.md — Workflow & UX Critic: phase transitions, unhelpful defaults, unnecessary friction

Triage subagent instructions: Return a JSON block with:

• critics: array of persona filenames — 1–3 by default, or exactly N (clamped per the --critics=N rule below) when that flag is set (e.g., ["senior-engineer.md", "contract-caller.md"])
• rationale: object mapping each filename to a one-sentence reason for selection
• target_summary: one sentence describing what the target does

Triage rules:

• If --no-specialists: select only from generics
• If --focus is a single word ≥6 chars that prefix-matches a specialist slug: always include that specialist
• If --critics=N is provided: select exactly N critics, clamped to the number of eligible personas (values above the catalog select every eligible persona instead; values below 1 are ignored). --critics=N overrides the re-challenge cap of 2.
• If re-challenge (yes): select max 2 critics total
• Otherwise: select 1–3 critics; include at least one generic unless the target is highly specialized
• If triage returns zero critics: fall back to senior-engineer.md

Write triage JSON to <tmpdir>/triage.md. Parse the result in the orchestrator context.

If empty $ARGUMENTS

Quick recon: directory structure, recently modified files (git log -n 10 --diff-filter=M --name-only --format=), largest files. Then:

AskUserQuestion:
  question: "I've scanned the codebase. These areas look most suspect. Which should I critique?"
  header: "Focus area"
  multiSelect: false
  options:
    - label: "<area 1>"
      description: "<why it looks suspect>"
    - label: "<area 2>"
      description: "<why it looks suspect>"
    - label: "Let me specify"
      description: "I'll tell you exactly what to look at"

Phase 2: Critique

Read selected persona files

For each persona filename from triage, resolve to the full path by searching ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/personas/generic/ then personas/specialist/. Verify each file has name and type in frontmatter and a non-empty body. Record validation issues to <tmpdir>/validation-warnings.md and exclude invalid files.

If the generic persona directory is missing or empty, stop with: "Cannot launch critics — persona files not found at ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/personas/generic/. Run uv run install.py."

Dispatch critics in parallel

Issue ALL critic Agent tool calls in a single response message. Each uses subagent_type: standard-worker, NOT run_in_background. Each critic receives:

• Target content (file paths to read, or inline text)
• Target type and target_summary from triage
• Full persona content (Persona, Characteristic question, Focus bullets)
• Triage rationale for why this critic was selected
• Focus instruction if --focus was provided: "The user is specifically concerned about: . Weight your analysis toward this concern."
• If re-challenge: "This is a re-challenge after fixes were applied. Focus on: (1) whether the fixes were thorough, (2) whether fixes introduced new problems, (3) issues missed in the first round."
• Project context if available: check the project's CLAUDE.md for frontmatter with audience, developers, and data-sensitivity fields. If present, include: "Project context: audience is , developer(s), data sensitivity is . Calibrate your findings to this context — skip findings that would only matter for a different audience or scale." If absent, do not fabricate context — omit this line.
• If target type is design-doc and the doc's **Status:** is archived or abandoned: "This design.md is frozen (Status: ) — it documents a past decision, not a live spec to keep synced with the code. Critique the decision as written, but do not flag drift from current code as a finding — that belongs in the doc's own ## Addendum section, not this critique."
• Output path: <tmpdir>/<persona-slug>-report.md
• Critic rules:
  1. Cite evidence for every claim — file:line for codebase claims; canonical URL for external patterns
  2. Name the problem directly — no hedging
  3. Propose a fix: Classification: Auto-apply | User-directed + one-sentence fix or options
  4. Tag each finding: severity (CRITICAL/HIGH/MEDIUM/TENSION), type, design-level
  5. Structure each finding: **Why it matters**, **Evidence**, **Design challenge**
  6. Include a Pushback section: findings you anticipate other critics raising that you'd disagree with
  7. Read beyond provided files: use Read, Grep, Glob; include Files examined at top of report

After all critics complete, verify each output file exists and has ≥500 bytes. Record undersized/missing files to <tmpdir>/validation-warnings.md.

Phase 3: Synthesize + Classify

Dispatch synthesis as a separate subagent (subagent_type: standard-worker) for fresh context.

The synthesis subagent receives:

• All critic report paths (<tmpdir>/<slug>-report.md for each critic)
• Triage rationale and target_summary
• Target type
• Output path: <tmpdir>/challenge-results.md
• Contents of <tmpdir>/validation-warnings.md if it exists
• The full synthesis procedure below

PRIMARY OBJECTIVE (include as opening paragraph): You MUST write a findings file to <output path> using the Write tool before you finish. If you do nothing else, write that file.

Synthesis procedure:

1. Read all critic reports in full — do not glob; read each named file explicitly
2. Group by problem area — cluster findings addressing the same concern. Keep similar-but-distinct issues separate.
3. Assign tags per finding:
   • severity: highest severity any critic assigned (must be CRITICAL / HIGH / MEDIUM / TENSION — reclassify non-contract values as MEDIUM)
   • type: type best describing the root cause
   • design-level: Yes wins when critics disagree
   • classification: Auto-apply only when ALL critics agree on the same fix AND it's localized and additive AND severity is not CRITICAL. Otherwise User-directed. When ambiguous, default User-directed.
   • visibility: presented for every finding
   • disposition: pending for every finding
4. CRITICAL guard: CRITICAL findings MUST always be classified as classification: User-directed regardless of the classification field from any critic or agreement level. This is a non-negotiable override — do not classify any CRITICAL finding as Auto-apply under any circumstances.
5. Copy presentation fields from critic reports: why-it-matters (most concrete consequence statement), evidence (all file:line citations, deduped), design-challenge (strongest question). Write not cited for evidence when none; omit other fields when absent.
6. Write recommendation for each User-directed finding (which option and why). For TENSION: write deciding-factor instead.
7. Validity assessment: assess whether each finding holds up. Findings are valid by default — to flag one as likely invalid, you must provide concrete evidence: what the finding claims, what the code actually does, and why they conflict. Read the relevant code to verify claims. If you cannot articulate the evidence trail, the finding stays in the main list. Move likely-invalid findings to the ## Likely Invalid section per the findings protocol; set each moved finding's visibility to likely-invalid and drop its disposition (omit the field — NULL). Renumber the remaining findings to stay contiguous (no gaps in the ## Finding N: sequence).

Write findings file to the output path using Format-version: 4 header. Include **Likely-invalid:** N in the header block (even when 0). Format per ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/findings-protocol.md.

After synthesis subagent completes: Verify the findings file exists at the output path. If missing (subagent returned text instead of writing), extract findings from the returned text: if it starts with # Challenge Findings and contains **Format-version:** write as-is (verify **Likely-invalid:** line is present; inject **Likely-invalid:** 0 after the **Format-version:** line if missing); if it contains ## Finding headings inject the header block (including **Likely-invalid:** 0) then write; otherwise stop with "Error: synthesis subagent did not produce findings in a writable format — re-run /mine-challenge."

Phase 4: Execute

Read the findings file. Announce: "Specialists selected: [names from triage]" and note re-challenge if applicable. For each critic excluded by validation, announce the exclusion before findings.

If --mode=passthrough: present a one-paragraph summary (count by severity, likely-invalid count, top takeaway). Return. Do not execute anything.

If standalone mode (direct user invocation, mine-grill, or any caller not passing --mode=passthrough — includes orchestration callers driven via challenge-gate.md):

Read and follow the Inline Resolution Flow in ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/findings-protocol.md exactly. After all findings are processed, report: "Applied N findings. M skipped. L flagged as likely invalid." List critic report paths and findings file path.

Principles

1. Evidence or silence — every claim must cite a specific file and line
2. Direct — name the problem, explain the consequence, move on
3. The better way — every finding must name a pattern, approach, or structural alternative
4. Impact over consensus — severity reflects consequence, not vote count
5. Err toward user input — ambiguous resolution → User-directed
6. CRITICAL → always user-directed — no exceptions

Known Callers

Passthrough callers (pass --mode=passthrough):

• skills/mine-research/SKILL.md
• skills/mine-brainstorm/SKILL.md

Standalone callers (full inline resolution flow):

• skills/mine-grill/SKILL.md

Orchestration callers (mandatory, via challenge-gate.md):

• skills/mine-define/SKILL.md (Phase 5.5 — design-time challenge)
• skills/mine-sketch/SKILL.md (Phase 4.5 — sketch-time challenge with --critics=2)
• skills/mine-orchestrate/post-execution-pipeline.md (Step 3.5 — ship-time challenge)

Inline-revision callers (invoke challenge, read findings in-context, revise own proposal):

• skills-impeccable/i-adapt/SKILL.md, skills-impeccable/i-animate/SKILL.md, skills-impeccable/i-bolder/SKILL.md
• skills-impeccable/i-clarify/SKILL.md, skills-impeccable/i-colorize/SKILL.md, skills-impeccable/i-delight/SKILL.md
• skills-impeccable/i-distill/SKILL.md, skills-impeccable/i-harden/SKILL.md, skills-impeccable/i-layout/SKILL.md
• skills-impeccable/i-overdrive/SKILL.md, skills-impeccable/i-optimize/SKILL.md, skills-impeccable/i-polish/SKILL.md
• skills-impeccable/i-quieter/SKILL.md, skills-impeccable/i-typeset/SKILL.md

Detection callers (scan for severity labels, don't read findings file):

• skills/mine-build/SKILL.md

To find all callers: grep -r 'CHALLENGE-CALLER' ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/ ${CLAUDE_CONFIG_DIR:-~/.claude}/skills-impeccable/ --include='*.md' -l