# Judge Plan > Lean standalone gate for reviewing create-issue plan artifacts before implementation. Use after `{ISSUE_DIR}/plan.md` exists to check format, proposal fidelity, actionability, and ETHOS alignment without doing architecture review or implementation. - Skill: `iamhenry/judge-plan` (Agent Skill) - Install (CLI): `npx skillmds@latest add iamhenry/judge-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/iamhenry/judge-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: iamhenry (https://skillmd.com/u/iamhenry) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/iamhenry/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: ```md ## 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: ```md ## 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.