prospect

/prospect — Plan pre-mortem with risk enforcement

Run a structured pre-mortem on a plan or approach that has been created but not yet executed. Forward-looking counterpart to /retrospect. Produces a 10-section markdown report with per-step verdicts, risk status, action recommendations, and process pre-mortem when the plan-formation itself was thin. Writes findings to knowledge/logs/prospect/ and runs aria's standard intake.

The discipline this enforces: before the first edit lands, every planned step gets named, its evidence base examined, its smallest viable version identified, and its action gated on the strength of the underlying hypothesis. Mirrors /retrospect's shape so the same review muscle works in both directions.

Step 0: Inputs & Mode Detection

Parse the invocation arguments. The first positional argument is the scope keyword; subsequent positional arguments are scope-specific. Six scopes plus a no-args default:

| Scope | Trigger | Backward-compat flag (still accepted) | Plan source | |---|---|---|---| | plan (default) | /prospect plan or /prospect | (was the no-arg default) | Current conversation's articulated plan — combine the active TodoWrite list, the most recent assistant plan/approach message, and any in-session plan file Claude has written. If ambiguous, ask user "Which of these is the plan you want me to pre-mortem?" with a short list. | | session | /prospect session | --session | Synonym for plan. Reserved for cases where the user wants to emphasize "everything articulated this conversation" rather than a single plan artifact. | | todos | /prospect todos | --todos | Just the active TodoWrite list — a thin mode for quick checks | | file | /prospect file <path> | --plan <path> | Read the markdown file at <path> as the plan | | linear | /prospect linear <id> | --linear <id> | Read the ticket's Technical Intake (and Product Intake for goal context) via Linear MCP. If MCP unavailable, ask user to paste. | | branch | /prospect branch <name> | --branch <name> | Uncommitted/unpushed local changes on the branch — git diff <main-branch>...<name> — treated as a plan-in-progress (NOT shipped yet) |

Argument parsing rules:

• If the first positional arg matches a scope keyword (case-insensitive), use it. Otherwise treat it as an arg to the default plan scope.
• Backward-compat flag forms (--plan, --linear, --branch, --todos, --session) remain accepted indefinitely. Both /prospect linear LINEAR-123 and /prospect --linear LINEAR-123 resolve identically.
• Modifier flags (apply to any scope): --linear-post (post the prospect verdict to detected Linear tickets at end), --no-source (skip Step 3.5's Evidence-Sourcing Pass), --lens=overbuild (run the over-build review pass — see "Over-build lens" section; opt-in, off by default).

After mode detection, gather:

1. Goal — Ask the user: "What is this plan supposed to accomplish? (One sentence is fine.)" If they don't reply, fall back to the plan's first heading or stated objective.
2. Tickets — Scan plan text/commits/branch name with regex \b([A-Z]{2,}-\d+)\b for Linear-style ticket IDs. If found AND Linear MCP is available, fetch each ticket's Product/Technical Intake + acceptance criteria to use as the goal-anchor in §4.6. If Linear MCP is unavailable, note "ticket context unavailable" but continue.
3. Pre-execution evidence — Ask the user: "For each step in this plan, do you have evidence the step is necessary and that the underlying assumption is correct? (✅ measured / ⚠ inferred / ❌ contradicted / ❓ untested)" Show the per-step list and accept inline replies. If user can't supply evidence for any step, mark those ❓ — those steps will resolve to DEFER unless §4.7 produces supporting hypothesis confidence.

If scope is branch (or invoked via --branch) and the diff is non-trivial (>50 LOC across >3 files), warn: "Branch already has substantive code — consider /retrospect range main..HEAD instead, which is calibrated for already-written changes." Continue if user confirms.

Step 0.5: Active Knowledge Surfacing

If the user's config (~/.claude/aria-knowledge.local.md) has active_knowledge_surfacing: true (default as of v2.15.0), surface relevant tagged knowledge BEFORE Steps 1-3 so loaded files inform pattern selection and evidence sourcing. If the field is false, skip this step entirely (note Active surfacing: disabled in the Anchor block).

Algorithm:

1. Build query. Combine, separated by spaces: the Goal sentence from Step 0; the plan's first heading or the first 3 TodoWrite items; any detected Linear ticket IDs (e.g., LINEAR-123); the file basename if scope is file; the branch name if scope is branch.

1. Read the index. Read <knowledge_folder>/index.md (resolve <knowledge_folder> from the config's knowledge_folder field). Parse the ## Tag Index section for ### tagname headers — that's the matching vocabulary (~77 known tags as of v2.15.0). Ignore the ## Other Tags section (freeform tier, intentionally excluded from auto-surfacing).

1. Tokenize. Lowercase the query, strip punctuation to spaces, dedupe to a word set.

1. Match. Exact word-vs-tag equality only — no substring, no fuzzy. Collect the set of matched tags.

1. Threshold gate. If fewer than 2 tags matched, note Active surfacing: 0 matches (below threshold) in the Anchor block and skip to Step 1. Single-tag matches are too noisy.

1. Collect files. Under each matched tag's ### tag section, gather the - path — description lines. Dedupe by path. Cap at top-5 by first-appearance order.

1. Ledger filter (best-effort). Run ls -t /tmp/aria-active-* 2>/dev/null | head -1 via Bash to find the current session's ledger (the most recently modified file matching that pattern). If found, read it and drop any matched paths already listed there — they were surfaced by an earlier hook/skill in this session. If no ledger exists, proceed unfiltered.

1. Read matched files. For each remaining path (up to 5), Read the full file into context.

1. Summarize. Before Step 1's Anchor Block, emit a 3-line surfacing block:

`` Active Knowledge Surfacing: Tags matched: <tag1> <tag2> ... Files loaded: <N> (<file1>, <file2>, ...) Relevance: <one sentence per file: why this informs the prospect> ``

1. Carry-forward. These loaded files become input to Step 2 (Load Pattern Libraries — past prospects/retros tagged with the same topic may already catalog the relevant patterns) and Step 3.5 (Evidence-Sourcing Pass — they may already validate or falsify assumptions in the plan, converting ⚠/❓ to ✅/❌ before the verdict round).

1. Tracked artifacts surfacing (added v2.16.1). After Step 10's carry-forward, ALSO surface CODEMAP + STITCH for the plan's project. The shared lib at ${CLAUDE_PLUGIN_ROOT}/bin/lib-tracked-artifacts.sh implements equivalent logic for hooks; this step inlines the algorithm for skill-context portability.

a. Detect project tag. Try in order: --group=<tag> from Step 0 if provided → first Linear-ticket ID prefix that maps to a projects_list tag → first projects_list[<tag>].path whose path appears as substring in the plan source path (from Step 0 Source: field). If no detection, skip the rest of Step 11.

b. Resolve project root via Bash. Parse projects_list: from ~/.claude/aria-knowledge.local.md frontmatter (comma-separated tag:path). For the detected tag, compute project_root = $HOME/Projects/<path>. If directory doesn't exist, skip.

c. CODEMAP directory load (if {project_root}/CODEMAP.md exists). Compute boundary via awk '/^## [0-9]+\.|^---$/ && NR>5 {print NR; exit}' "{project_root}/CODEMAP.md"; Read limit = (end - 1) (fallback 50 if awk empty). Compute age = (today - mtime).days; read codemap_staleness_threshold_days (default 14). If `age > 2*threshol