validate-issue

validate-issue

Validate every current-behavior claim against code. Treat cited roots, lines, fixes, and prior verdicts as claims that need independent proof. Return one decision that covers behavior, cause, evidence, proposal, scope, and fix.

Input

Accept a full issue URL, #N, N, or owner/repo#N. With no input, resolve the newest open issue in the current repo and state the selected number.

0. Establish the default-branch baseline

Do not create a worktree for validation or issue edits. Resolve and refresh the current default branch:

DEFAULT=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
git fetch origin "$DEFAULT"
git branch --show-current
git rev-list --left-right --count "origin/$DEFAULT...HEAD"

Read working-tree files only at 0 0, or when git diff --name-only HEAD "origin/$DEFAULT" excludes every inspected path. Otherwise use git show "origin/$DEFAULT":<path>. State the baseline in the verdict.

1. Fetch the issue and linked pull requests

Always fetch the body and comments with gh issue view <N> --comments. For omitted input, first resolve gh issue list --limit 1 --json number --jq '.[0].number'. Then inspect the issue timeline for cross-referenced pull requests; comment output does not include them:

gh api "repos/<owner>/<repo>/issues/<N>/timeline" --paginate \
  --jq '.[] | select(.event == "cross-referenced" and .source.issue.pull_request) | .source.issue'

Verify merged fixes against current code and recommend closure or reuse. List overlapping open work under Concerns.

2. Extract claims and proposal assertions

List each concrete current-behavior claim, including named causes, citations, sets, negatives, and benefit premises. Separately extract proposal goals, lifetime, population timing, benefits, consumers, failure policy, deployment surface, and touched sites. Run steps 5a and 5b for a new subsystem, shared state, cross-cutting refactor, deduplication, single source of truth, multi-consumer coordination, or infrastructure analogy.

3. Verify every claim

Trace each scenario through its conditions and configuration. Apply every triggered depth rule:

1. Named wrapper/helper: read its body and delegated or short-circuit paths.
2. Set claim: find real call sites, establish membership, and diff the claimed set.
3. Benefit claim: prove the broken baseline still exists with code, comments, and relevant history.
4. Conjunction or negative: split atomic assertions and prove absence across all paths.
5. Negative over a window: trace the complete event-to-boundary dispatch and every possible producer.
6. Superlative, method-over-set, or cited baseline: establish the full population, actual tool coverage, and source history.
7. Aggregate, dedupe, prorate, or shared state: verify its partition boundary and key against the proposed scope.
8. Missing, undocumented, or unhandled surface: read surrounding content, find stale old copy, and diff the deliverable file list.

Evidence outranks every verdict. Reconcile evidence across all bullets and your own paired findings before finalizing.

4. Mark each claim

Use ✅ Verified, ❌ Refuted, ⚠️ Conditional, or ❓ Unverified. Cite file:line for each located path, name conditions, and retain every unresolved claim.

5. Assess the proposal

Lead Proposal with a ≤55-word ASD-STE100 Goal that states the outcome. Assess claims before design; a refuted premise can make the proposal unnecessary.

5a. Architecture

For every non-trivial proposal identified in step 2, read architecture.md completely and apply it after claim tracing.

5b. Self-consistency

Whenever step 5a runs, also read proposal-consistency.md completely and apply it to the issue text.

5c. General checks

Use git log --since=7.days on touched paths. Check locking, migrations, reloads, idempotency, failure blast radius, parallel live/offline/admin paths, dual implementations, and regression of recent work. Put each material finding under Concerns with file:line; any safety, recent-work, or parity defect makes the issue require an update.

6. Score complexity

Read complexity-scoring.md completely on every validation. Derive axes from the traced edit and test list. The canonical formula is:

1. Capability maps max(Risk, Uncertainty) as 0–1 → 0, 2 → 1, 3 → 2, 4 → 3. If Coupling ≥ 3, use at least Capability 2.
2. Volume is (Scope + Coupling + Verification) × 2.
3. Score is 25 × Capability + Volume (0–99 under current axis bounds).

The fableplan signal is yes when the score is 61 or higher. It is no below 61.

The first review escalates on its own, coarser scale, so its boundaries do not line up with the bands above:

A missing score reviews on the heaviest row (Fable) because the complexity is unknown. "Missing" means the title carries no [C<score>] prefix at all. A literal [C0] is a real score — every axis graded 0 — so it takes the 0–9 build band and the 0–10 first-review row like any other score. Fable reviews the first cycle only: after a Fable first review, the blocking re-reviews step down one rung each — @claude opus review for the first, @claude review for every one after that. The ladder stops at @claude review; it never steps down to Sonnet, because a C81+ change keeps a capable reviewer however many cycles it takes. The step-down is keyed to the reviewer that actually ran cycle 1, and the score band does not decide it: a Fable first review steps down however it was selected — the 81–99 row, or a stamped PR review: line naming Fable at any score — while a first review on any other model keeps its own model for every blocking re-review. A pass that addressed only non-blocking findings drops to @claude sonnet review without consuming a rung.

Report only N/100 — Capability <k> (<driver>); Volume <v> · fableplan: <yes|no> plus the traced edit list.

7. Decide scope disposition

A high score alone is acceptable. Narrow speculative scope whenever needed. Split and Umbrella candidates must pass all three gates:

1. Each part can ship, pass tests, and deliver value in its own pull request.
2. Fold each part below C41 into the parent. At least two remaining parts must each score C41 or higher. Any folded part forces Umbrella. If fewer than two remain, keep one issue; emit OK — restructure as in-body checklist and require an update when its body lacks that checklist.
3. The combined diff is roughly above 500 changed lines, the parts route to different score bands, or one part has money, data-integrity, or security risk.

Keep one issue when any gate fails or one root cause requires one diff. Use Split for independent parts with no folded work and Umbrella for coordinated parts or any folded work. Narrow remains available regardless of these gates; cut to the core and move optional work to a Future note. Every proposed child needs its own scored title, problem, and acceptance criteria. Scope and description-update decisions remain independent.

8. Output the verdict

Use this structure and omit empty optional sections:

Claims:
- <status> <claim> — <evidence>
Architecture:                         # only when 5a ran
- <status> <placement/owner/medium> (<dispatch file:line>)
- Optimal: <required for ⚠️/❌>
Concerns:                             # only when present
- <concern> (<file:line>)
Proposal:
- Goal: <plain simple English, ≤55 words>
- <status> <consistency gap>          # only when 5b is not ✅
Scope:                                # only when too large or checklist restructure applies
- <disposition> — <reason and parts>
**#<N>: Update issue description? <Yes | No>** · Complexity: <score>/100 — Capability <k> (<driver>); Volume <v> · fableplan: <yes|no> · Scope: <OK | too large — split/umbrella/narrow>
<specific edits when Yes>
<next-step line — see the rule below; it carries its own leading arrow>

Set Yes for a material ❌/⚠️ claim, architecture or consistency gap, material concern, missing scope, or required checklist restructure. Set No only when the issue is accurate, feasible, consistent, complete, and ready. Always offer fableplan when its signal is yes; if the user chooses work first, ask once whether to plan or build directly.

Next-step line. The line always leads with the action this verdict recommends, then lists the other options. Match the first case that applies, then take the variant for the fableplan signal, and post that line verbatim — each one already carries its leading → and is complete as written. Never assemble the line by deleting words from another variant.

1. Scope disposition is split or umbrella:
   • fableplan yes → → Recommend "split issue" to restructure; or "update issue" to edit, "work on issue" to build as-is, "fableplan" to plan first.
   • fableplan no → → Recommend "split issue" to restructure; or "update issue" to edit, "work on issue" to build as-is.
2. Update issue description is Yes:
   • fableplan yes → → Recommend "update issue" to apply the edits above; or "work on issue" to build as-is, "fableplan" to plan first.
   • fableplan no → → Recommend "update issue" to apply the edits above; or "work on issue" to build as-is.
3. Otherwise:
   • fableplan yes → → Reply "work on issue" to proceed, "update issue" to edit, or "fableplan" to plan first.
   • fableplan no → → Reply "work on issue" to proceed, or "update issue" to edit.

9. Handle "work on issue"

Invoke work-on-issue with the issue number. It owns worktree creation through the open closing pull request. Surface any step-7 scope disposition before handoff.

10. Handle "fableplan"

Invoke fableplan with the issue number. It owns planning, posting the issue comment, and asking whether to build. Honor an explicit request even when the signal is no.

11. Handle "update issue"

Read issue-editing.md completely, then apply its verified title/body procedure from the current checkout without a worktree.

Red flags