Judge Plan

Judge Plan

Use this skill after create-issue writes a local plan artifact and before any implementation starts.

Use a fresh session separate from the plan author and proposal judge, even for a short plan. Scale depth, not independence: brief required sections suffice for known small work; expand scrutiny for uncertain or consequential changes. Do not demand diagrams, multiple phases, or prose with no decision value. For standalone review, accept the approved proposal/intent directly instead of requiring pipeline issue.md; pipeline gaps still go to their owners.

Keep the scope narrow:

• Check whether agents can safely execute the plan.
• Confirm the plan follows the selected proposal from issue.md, using research as supporting evidence if needed.
• Catch malformed markdown, missing required structure, vague tasks, and obvious ETHOS drift.
• Write the decision back into plan.md.

Do not use this skill for broad architecture review, redesign, implementation, code edits, commits, or separate review files.

Inputs

Read only these artifacts when available:

• {ISSUE_DIR}/issue.md
• {ISSUE_DIR}/plan.md
• {ISSUE_DIR}/research/*.md
• _ai/docs/ETHOS.md
• .agents/commands/workflow/01-plan/02-create-issue.md as the structural reference

If the task directory or plan.md is missing, return ASK_USER with the missing artifact and its owner (gather-context for the directory, create-issue for the plan). The caller routes bounded repair from approved context rather than asking the user to author it. Missing intent or permission still requires a user decision.

Artifact Contract

The plan must be a create-issue style artifact for {ISSUE_DIR}/plan.md and include enough structure for a follow-on implementation agent to execute without guessing.

ISSUE_DIR is the artifact directory created by gather-context for the current pipeline run.

Required major sections:

• Acceptance Criteria with measurable checkbox criteria
• User Story and Gherkin BDD Scenarios in valid markdown fences
• Scope and Boundaries
• Codebase Orientation, Dependencies, and relevant data flow/model/architecture notes (brief inapplicability is enough when unaffected)
• Deliverables and Error Handling
• Implementation Checklist with atomic tasks and concrete file paths or locations; phases when useful
• Verification Target with Platform (legacy Verification Mode), Objective, Primary Flow, Regression Check, Mechanical, Observable, Pass Criteria, and Blocked Conditions

Review Steps

1. Locate the chosen proposal in issue.md, especially ## Judge Decision and/or ## Approaches; use research/*.md only as supporting evidence.
2. Check plan.md against the create-issue structure, especially acceptance criteria, Gherkin scenarios, implementation checklist, and verification gate plan.
3. Check proposal fidelity: the plan must implement the selected proposal and not silently switch approach.
4. Check actionability: tasks must be concrete enough for a junior implementation agent, with files, actions, and verification.
5. Check markdown parse safety: headings, lists, tables, and fenced code blocks must be well-formed enough that agents will not misread the plan.
6. Check ETHOS lightly when present; otherwise use existing project and safety instructions without requiring a new ETHOS file. Prefer tracer-bullet scope, reuse, user trust, safe failure, and minimal friction. Do not re-litigate architecture unless the plan contradicts these principles in a blocking way.

Scorecard

Score out of 100:

• Scoring anchors: full credit means the plan clearly satisfies the item with artifact evidence; half credit means partial satisfaction or thin evidence; zero means missing, contradicted, or unverifiable.
• Create-issue structure: 40
  • 10 required major sections exist.
  • 10 acceptance criteria and Gherkin are measurable, testable, and markdown-valid.
  • 10 implementation checklist uses action prefixes and files or locations; phases only when useful.
  • 10 verification target includes Platform (legacy Verification Mode), Objective, Primary Flow, Regression Check, Mechanical, Observable, Pass Criteria, and Blocked Conditions. Mechanical must fail when a relevant machine-checkable condition is unmet; together the declared lanes must distinguish the Objective from a likely false positive. Do not require an end-to-end test framework when an existing content/asset assertion plus actual-surface evidence suffices. Observable must be a retained path, or n/a only when platform is non-ui.
• Proposal fidelity: 35
  • 15 plan implements the selected approach.
  • 10 plan does not drift into unselected scope.
  • 5 plan preserves stated out-of-scope boundaries.
  • 5 plan uses research constraints and repo style evidence.
• Actionability: 20
  • 8 tasks identify files or locations.
  • 6 tasks are atomic enough for implementation agents.
  • 4 verification steps are concrete, including a named Mechanical command.
  • 2 risks or blockers are clear.
• Style alignment: 5
  • 5 follows create-issue formatting and repo planning style.

Hard Fail Rules

Return REVISE_PLAN regardless of score if any are true:

• A major required section is missing.
• The plan contradicts or drops the chosen proposal.
• Implementation tasks are too vague to execute safely.
• Markdown structure is broken enough that agents may misread it, including malformed fences around Gherkin or code examples.
• Mechanical is missing, vague (no named command), or not machine-checkable. Missing Mechanical on an older in-flight plan is REVISE_PLAN, not ASK_USER.
• Platform is web, mobile-web, ios, or macos and Mechanical is only lint, typecheck, format, or compile. Those may appear as extra commands, not as the sole oracle.
• Platform is web, mobile-web, ios, or macos and Observable is missing, n/a, or has no retained evidence path.

Return APPROVE_PLAN when no hard fail applies and the score is 85 or higher.

Return REVISE_PLAN when a hard fail applies, or when artifacts are sufficient to revise but the score is below 85.

Return ASK_USER when required artifacts are missing, product intent is ambiguous, the selected proposal is ambiguous, or the judge cannot distinguish between valid competing approaches from the existing artifacts.

Writeback Rule

Append or update one concise ## Plan Judge section at the end of plan.md. Do not create a separate review file.

For an explicit no-edits review, return the same decision in chat with Writeback: not authorized; do not mutate the plan. A delivery caller must obtain authorized owner writeback before relying on a pipeline artifact gate.

If a ## Plan Judge section already exists, replace that section only. Preserve the rest of plan.md exactly.

Use this structure:

## Plan Judge

- Decision: `APPROVE_PLAN|REVISE_PLAN|ASK_USER`
- Score: [0-100]
- Chosen proposal: [one sentence]
- Checked: [issue.md, plan.md, research files, ETHOS, create-issue reference as applicable]

### Notes

- [approve note or required revision]
- [approve note or required revision]

### Required Changes

- [Only for REVISE_PLAN or ASK_USER; otherwise `None`]

Output

After writing plan.md, return this exact structure in chat:

## Plan Judge Result

- Decision: `APPROVE_PLAN|REVISE_PLAN|ASK_USER`
- Score: [0-100]
- Plan: `{ISSUE_DIR}/plan.md`
- Writeback: `## Plan Judge` appended or updated

### Key Findings

- [highest-signal finding]
- [highest-signal finding]

### Next Action

- [implement / revise plan / ask user to choose proposal or provide artifact]

Constraints

• Do not edit application code.
• Do not implement the plan.
• Do not broaden into architecture review or redesign.
• Do not create helper files, references, or separate review artifacts.
• Do not commit changes.
• Keep review notes concise and tied to the artifacts.