Grade an implementation plan on a 0-10 scale using the plan-grader rubric. This skill is
content-only: inspect, score, explain, and produce a paste-back prompt. Do not edit files, run
formatters, commit changes, or implement the plan being graded.
Use when the user asks to grade, score, review, evaluate, improve, or calibrate a plan, especially
plans produced by Claude Code, Codex, GitHub Copilot, Gemini CLI, or similar agentic CLIs. Also
trigger directly via /plan-grader.
Inputs
$ARGUMENTS may be any of:
<path> or file:<path>: read the plan from a local Markdown/text file.
"..." or text:"...": grade the quoted inline plan text exactly as provided.
latest claude plan, latest codex plan, latest copilot plan, or latest gemini plan:
discover candidate plan/session files using references/plan-discovery.md.
- Optional
--json: emit only the structured JSON object described below.
- Optional
--blind: strip source-agent attribution before scoring. Keep explicit harness context
that affects safety, validation, or repo fit.
If the input is ambiguous, ask for the plan path or paste. Do not guess a plan from unrelated chat.
Reference Order
Before grading, read these references:
references/rubric.md
references/context-resolution.md
references/plan-discovery.md when discovery, imports, symlinks, oversized content, or
transcript extraction are involved
references/agent-formats.md when the source agent is known or a paste-back prompt is needed
- Relevant examples in
references/calibration-plans/
Workflow
Parse flags and input mode.
--json changes output format only.
--blind removes agent identity from the plan before scoring.
file: forces file mode.
text: forces inline text mode.
- Top-level quoted text is inline plan text, not a path.
Resolve the plan text.
- For file inputs, read the target file.
- For inline text, use the supplied text verbatim.
- For
latest <agent> plan, follow references/plan-discovery.md.
- If discovery returns multiple candidates, present the top three most recent candidate paths and
ask the user to choose.
- Refuse oversized inputs that cannot fit the context budget. Do not silently truncate.
Resolve intent sources.
- Treat files mentioned by the plan as intent evidence, especially
@roadmap.md,
@spec.md, file:docs/foo.md, or explicit local paths.
- Resolve transitive
@ imports to the depth documented in references/plan-discovery.md.
- If a referenced intent file is unreadable, record the missing file and lower confidence.
- If a readable intent file contradicts the plan, apply the relevant rubric cap.
Resolve harness context.
- Read project-level
AGENTS.md first as the cross-agent baseline when present.
- Layer agent-specific project overrides:
CLAUDE.md, GEMINI.md,
.github/copilot-instructions.md, .github/instructions/*.instructions.md, and
AGENTS.override.md.
- Consider user/global harness files only as preference context. They cannot weaken repo-local
safety, validation, protected-path, release, or CI rules.
- Detect whether the plan violates configured harnesses or protected gates.
Calibrate before scoring.
- Read at least the two calibration anchors closest to the expected score band.
- Use the anchors to normalize severity and avoid over-rewarding format polish.
Score the plan.
- Score each rubric dimension from 0 to 10.
- Compute the weighted score using rubric version
2.0.0.
- Apply caps, then auto-reject rules, then floor at 0, then round to one decimal.
- Record
confidence as high, medium, or low.
Produce output.
- Default: concise human-readable report with score, verdict, dimension table, caps, blocking
gaps, non-blocking polish, and a paste-back prompt.
--json: emit only valid JSON with exactly these top-level keys:
rubric_version, score, verdict, confidence, dimensions, caps_fired,
blocking_gaps, non_blocking, paste_back_prompt.
Human Output Shape
Plan grade: X.X / 10
Verdict: <approve | approve with minor changes | revise before execution | reject>
Confidence: <high | medium | low>
<One short paragraph explaining the main reason for the grade.>
| Dimension | Weight | Score | Reasoning |
| --------- | -----: | ----: | ---------------------- |
| ... | 0.XX | N/10 | Evidence-backed reason |
Caps fired:
- <cap id or "None">
Blocking gaps:
1. <gap>
Non-blocking improvements:
- <improvement>
Paste-back prompt:
<agent-aware prompt from references/agent-formats.md>
JSON Output Shape
{
"rubric_version": "2.0.0",
"score": 8.4,
"verdict": "approve with minor changes",
"confidence": "high",
"dimensions": [
{
"name": "Goal and scope clarity",
"weight": 0.15,
"score": 9,
"reasoning": "The plan defines the output contract and non-goals.",
"evidence": ["plan.md:12"]
}
],
"caps_fired": [],
"blocking_gaps": [],
"non_blocking": ["Add one explicit smoke test for malformed input."],
"paste_back_prompt": "Revise the plan to add one malformed-input smoke test..."
}
Rules
- Do not mutate files or implement the plan being graded.
- Do not score from vibes. Cite concrete evidence from the plan, intent files, harness files,
repo paths, tests, CI, or explicit missing evidence.
- Mention when the grade is based on incomplete transcript extraction rather than a real plan file.
- Auto-reject dangerous caps even when the weighted score is high.
- Keep all weights from
references/rubric.md exactly. Do not silently reweight.
- For
--blind, do not penalize or reward the plan because it came from Claude, Codex, Copilot, or
Gemini. Grade the content and repo fit.
- If a plan references images or diagrams, do not OCR them. Mark that portion partially ungradable.
- If a plan would touch protected paths, verify it includes the required Spec ID or No-spec
rationale in the PR plan.
- Always include a paste-back prompt unless the user explicitly asks for only the numeric grade.
1---2# dotbabel:generated projection=sha256:48fafb297c2b84273c2179d6babef02b3f26292b7ec633f46a6adbe4f3cf475e source=skills/plan-grader/SKILL.md — do not edit directly3allowed-tools: Read Grep Glob Bash4argument-hint: '[--json] [--blind] <plan-path | file:<path> | text:"plan" | "plan" | latest <agent> plan>'5description: |6 Grade implementation plans on a 0-10 scale without mutating the workspace. Accepts plan files, quoted inline plans, or best-effort latest-plan discovery for Claude, Codex, Copilot, and Gemini.7name: plan-grader-38metadata:9 source: https://skillmd.com/skills/kaiohenricunha/plan-grader-310---1112Grade an implementation plan on a 0-10 scale using the plan-grader rubric. This skill is13content-only: inspect, score, explain, and produce a paste-back prompt. Do not edit files, run14formatters, commit changes, or implement the plan being graded.1516Use when the user asks to grade, score, review, evaluate, improve, or calibrate a plan, especially17plans produced by Claude Code, Codex, GitHub Copilot, Gemini CLI, or similar agentic CLIs. Also18trigger directly via `/plan-grader`.1920## Inputs2122`$ARGUMENTS` may be any of:2324- `<path>` or `file:<path>`: read the plan from a local Markdown/text file.25- `"..."` or `text:"..."`: grade the quoted inline plan text exactly as provided.26- `latest claude plan`, `latest codex plan`, `latest copilot plan`, or `latest gemini plan`:27 discover candidate plan/session files using `references/plan-discovery.md`.28- Optional `--json`: emit only the structured JSON object described below.29- Optional `--blind`: strip source-agent attribution before scoring. Keep explicit harness context30 that affects safety, validation, or repo fit.3132If the input is ambiguous, ask for the plan path or paste. Do not guess a plan from unrelated chat.3334## Reference Order3536Before grading, read these references:37381. `references/rubric.md`392. `references/context-resolution.md`403. `references/plan-discovery.md` when discovery, imports, symlinks, oversized content, or41 transcript extraction are involved424. `references/agent-formats.md` when the source agent is known or a paste-back prompt is needed435. Relevant examples in `references/calibration-plans/`4445## Workflow46471. Parse flags and input mode.48 - `--json` changes output format only.49 - `--blind` removes agent identity from the plan before scoring.50 - `file:` forces file mode.51 - `text:` forces inline text mode.52 - Top-level quoted text is inline plan text, not a path.53542. Resolve the plan text.55 - For file inputs, read the target file.56 - For inline text, use the supplied text verbatim.57 - For `latest <agent> plan`, follow `references/plan-discovery.md`.58 - If discovery returns multiple candidates, present the top three most recent candidate paths and59 ask the user to choose.60 - Refuse oversized inputs that cannot fit the context budget. Do not silently truncate.61623. Resolve intent sources.63 - Treat files mentioned by the plan as intent evidence, especially `@roadmap.md`,64 `@spec.md`, `file:docs/foo.md`, or explicit local paths.65 - Resolve transitive `@` imports to the depth documented in `references/plan-discovery.md`.66 - If a referenced intent file is unreadable, record the missing file and lower confidence.67 - If a readable intent file contradicts the plan, apply the relevant rubric cap.68694. Resolve harness context.70 - Read project-level `AGENTS.md` first as the cross-agent baseline when present.71 - Layer agent-specific project overrides: `CLAUDE.md`, `GEMINI.md`,72 `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, and73 `AGENTS.override.md`.74 - Consider user/global harness files only as preference context. They cannot weaken repo-local75 safety, validation, protected-path, release, or CI rules.76 - Detect whether the plan violates configured harnesses or protected gates.77785. Calibrate before scoring.79 - Read at least the two calibration anchors closest to the expected score band.80 - Use the anchors to normalize severity and avoid over-rewarding format polish.81826. Score the plan.83 - Score each rubric dimension from 0 to 10.84 - Compute the weighted score using rubric version `2.0.0`.85 - Apply caps, then auto-reject rules, then floor at 0, then round to one decimal.86 - Record `confidence` as `high`, `medium`, or `low`.87887. Produce output.89 - Default: concise human-readable report with score, verdict, dimension table, caps, blocking90 gaps, non-blocking polish, and a paste-back prompt.91 - `--json`: emit only valid JSON with exactly these top-level keys:92 `rubric_version`, `score`, `verdict`, `confidence`, `dimensions`, `caps_fired`,93 `blocking_gaps`, `non_blocking`, `paste_back_prompt`.9495## Human Output Shape9697```markdown98Plan grade: X.X / 1099Verdict: <approve | approve with minor changes | revise before execution | reject>100Confidence: <high | medium | low>101102<One short paragraph explaining the main reason for the grade.>103104| Dimension | Weight | Score | Reasoning |105| --------- | -----: | ----: | ---------------------- |106| ... | 0.XX | N/10 | Evidence-backed reason |107108Caps fired:109110- <cap id or "None">111112Blocking gaps:1131141. <gap>115116Non-blocking improvements:117118- <improvement>119120Paste-back prompt:121<agent-aware prompt from references/agent-formats.md>122```123124## JSON Output Shape125126```json127{128 "rubric_version": "2.0.0",129 "score": 8.4,130 "verdict": "approve with minor changes",131 "confidence": "high",132 "dimensions": [133 {134 "name": "Goal and scope clarity",135 "weight": 0.15,136 "score": 9,137 "reasoning": "The plan defines the output contract and non-goals.",138 "evidence": ["plan.md:12"]139 }140 ],141 "caps_fired": [],142 "blocking_gaps": [],143 "non_blocking": ["Add one explicit smoke test for malformed input."],144 "paste_back_prompt": "Revise the plan to add one malformed-input smoke test..."145}146```147148## Rules149150- Do not mutate files or implement the plan being graded.151- Do not score from vibes. Cite concrete evidence from the plan, intent files, harness files,152 repo paths, tests, CI, or explicit missing evidence.153- Mention when the grade is based on incomplete transcript extraction rather than a real plan file.154- Auto-reject dangerous caps even when the weighted score is high.155- Keep all weights from `references/rubric.md` exactly. Do not silently reweight.156- For `--blind`, do not penalize or reward the plan because it came from Claude, Codex, Copilot, or157 Gemini. Grade the content and repo fit.158- If a plan references images or diagrams, do not OCR them. Mark that portion partially ungradable.159- If a plan would touch protected paths, verify it includes the required Spec ID or No-spec160 rationale in the PR plan.161- Always include a paste-back prompt unless the user explicitly asks for only the numeric grade.