Agent-Skills.md

Agent Skills: 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.

UncategorizedID: iamhenry/ai-project-starter-kit/judge-plan
53

Install this agent skill to your local

pnpm dlx add-skill https://github.com/iamhenry/ai-project-starter-kit/tree/HEAD/.agents/skills/judge-plan

Skill Files

Browse the full folder contents for judge-plan.

Download Skill

Loading file tree…

.agents/skills/judge-plan/SKILL.md

Skill Metadata

Name
judge-plan
Description
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.

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 readable Gherkin BDD Scenarios, preferably 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, Falsifier, 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, Falsifier, Primary Flow, Regression Check, Mechanical, Observable, Pass Criteria, and Blocked Conditions. Mechanical covers relevant mechanical health or a machine-checkable condition; together the declared lanes must distinguish the Objective from its Falsifier. Existing build/lint/typecheck plus independent actual-product evidence can suffice for simple UI work. Additional assertions should protect distinct changed failure modes, not satisfy a template. Observable must be a retained path, or n/a only for a genuinely internal non-ui change with no changed user or consumer-observable behavior.
  • 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 obscures meaning, makes execution ambiguous, or violates an explicitly required consumer format. Missing or imperfect fences alone are not a hard fail when the content remains unambiguous and no consumer requires them.
  • 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.
  • Falsifier is missing or does not name an observation that would disprove the Objective.
  • The combined Mechanical and Observable checks cannot distinguish the Objective from its Falsifier, or omit a distinct consequential failure mode of the change. Do not reject a simple UI plan solely because its Mechanical command is build/lint/typecheck when independent actual-path proof covers the behavior.
  • Platform is web, mobile-web, desktop, ios, android, or macos and Observable is missing, n/a, or has no retained evidence path.
  • Platform is web, mobile-web, desktop, ios, android, or macos and Observable can be satisfied by a terminal, test runner, CI page, logs, source inspection, or another non-product substitute rather than the app-owned result of the Primary Flow.
  • The plan labels behavior available through a product UI or real consumer interface as non-ui because the changed implementation files are not UI files.
  • The task changes user or consumer-observable behavior but the plan permits completion from Mechanical evidence alone.

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

Report harmless presentation defects as nonblocking notes, not required revisions. They alone must not lower an otherwise executable plan below the approval threshold.

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.