fagan-inspection-beads

name	fagan-inspection-beads
description	Run a Fagan Inspection and create Beads issues from the defect log. Use when the user wants a structured findings-first review plus actionable Beads tracking for the resulting defects. Converts defects into trackable Beads tasks with priorities, structured fields, and parent-child dependencies.

Run a Fagan Inspection on the current change set, then create Beads issues from the defect log so defects become trackable tasks.

This is an add-on to fagan-inspection. Run the full five-phase inspection first, produce the consolidated defect log, then pipe defects into Beads.

Operating rules

• Default to review mode, not implementation mode. Do not edit code unless the user explicitly asks for rework after the inspection.
• Prefer findings about bugs, regressions, missing tests, design risks, and operational hazards over summaries.
• When subagents are available, use them only for independent domain reviews. Keep scope selection, synthesis, severity decisions, and Beads creation local.
• Keep commands non-interactive. Use bd create, bd update, bd dep add, and bd ready --json; never rely on editor-based flows.

---

Phase 1: Run the Fagan Inspection

Execute all five phases of a standard Fagan Inspection (scope, plan, domain reviews, synthesis, rework). Produce the full Fagan Inspection Report with the consolidated defect log table before proceeding.

Use existing chat context for intent and acceptance criteria. If missing, derive scope from git (status, staged/unstaged diff, PR-range diff vs origin/main or origin/master).

Inspection phases (same as core skill)

A) Scope -- Summarize impacted modules/files and externally visible behavior changes.

B) Plan -- Define Entry/Exit Criteria. Choose reviewer domains dynamically (correctness, security, performance, reliability, API/design, tests, docs, ops, data/migrations, concurrency, UI). Spawn parallel subagents per independent domain if supported; otherwise run sequentially.

C) Preparation -- Each domain reviewer outputs defects with: Title, Severity (MAJOR|MINOR), Domain, Location (file:line or symbol), What/Why + Evidence, Fix (specific change), Verify (test/command/scenario).

D) Synthesis -- De-duplicate, re-severity, prioritize. Produce a single defect log + rework plan.

E) Rework -- Fix MAJOR first if write permissions allow; otherwise give patch-level edits. Re-run checks/tests. Confirm Exit Criteria.

---

Phase 2: Beads Integration

Step 1 -- Detect Beads

Check if the bd CLI is available:

command -v bd

If bd is not found: Stop here. Output the Fagan Inspection Report only, and append:

## Beads Integration: Skipped

`bd` CLI not found. To install Beads and create trackable issues from this defect log:

  pip install beads-cli
  # or see https://github.com/steveyegge/beads

Then re-run: /fagan-inspection-beads

If bd is found: Continue to Step 2.

Step 2 -- Initialize Beads (if needed)

Check if the repo is already initialized:

bd ready --json

If that fails (no .beads/ directory, not initialized):

bd init --stealth

Use --stealth so Beads metadata is not committed to the main repo. This keeps the integration non-invasive.

Step 3 -- Create parent inspection issue

Create one parent issue to group all defects from this inspection:

bd create "Fagan Inspection: <current-branch> — <short-summary-of-scope>" -p 1 --json

Capture the parent issue ID from the JSON output. Store scope, intent source, and exit criteria in the parent:

bd update <parent-id> --description "<1-2 sentence scope summary>" --acceptance "<exit criteria from the inspection>" --notes "Inspection date: <today>. Intent source: <chat|git>. Domains reviewed: <list>."

Step 4 -- Create child issues per defect

For each defect in the consolidated defect log:

MAJOR defects -- always create:

bd create "[MAJOR] <defect-title>" -p 0 --json

MINOR defects -- create only if the user passed --include-minor in the invocation arguments. Otherwise skip and note them in the output.

For each created issue, immediately update with structured fields (do NOT use bd edit which opens an interactive editor):

bd update <child-id> --description "<what/why + evidence>" --notes "Domain: <domain>. Location: <file:line>. Evidence: <repro steps>." --acceptance "<verify steps from defect>"

Then link child to parent:

bd dep add <child-id> <parent-id>

Step 5 -- Claim and verify

After all issues are created, show actionable next steps:

bd ready --json

---

Output

Return a combined report with two sections:

Section A: Fagan Inspection Report

1. Scope & intent source (chat or git)
2. Entry/Exit criteria
3. Overview + top risks
4. Defect log (table: ID | Sev | Domain | Location | Title | Status | Fix/Next)
5. Rework summary (if applied)
6. Verification evidence (commands/tests)

List findings first in the final response. If no defects are found, say that explicitly and skip Beads creation unless the user asked for tracking-only output.

Section B: Beads Integration Summary

1. Status: initialized | already-initialized | skipped (with reason)
2. Parent bead: <id> -- <title>
3. Created defect beads: table of Bead ID | Severity | Defect Title | Priority
4. Skipped defects: list with reasons (e.g., "MINOR, --include-minor not set")
5. Next actions: output of bd ready --json