{"id":"5a592720-e760-4378-ae8c-99749c4fc14b","shortId":"YMbUnX","kind":"skill","title":"review-plan","tagline":"Use when the user asks to review the plan, sanity-check the plan, vet the plan, evaluate the plan, \"is this plan ready\", feasibility check on a plan, \"review-plan PATH\", or when another skill (like implement-plan) requests pre-flight plan evaluation before execution. Do NOT use w","description":"# Plan Review\n\nPre-flight review of an implementation plan markdown file. Produces a verdict (`READY` / `NEEDS_REVISION` / `BLOCKED`) and a prioritized findings table. Used standalone and as a pre-execution gate by `implement-plan`.\n\nThis is a **document** review, not a code review. No static analyzers. No diff scoping. The plan is treated as the artifact under test; the codebase is read-only context for feasibility checks.\n\n## Workflow\n\n### 1. Resolve the plan file\n\nPriority order:\n1. Explicit path from the invocation (e.g. `/review-plan docs/plans/auth-rewrite.md`).\n2. `./PLAN.md` in the current working directory.\n3. Latest by mtime in `./docs/plans/*.md` (typically `YYYY-MM-DD-<feature>.md` per convention).\n\nIf none resolve, stop and ask the user for a path. Do not guess.\n\n### 2. Load context\n\n- Read the resolved plan file fully.\n- Read any docs the plan references inline (`./REVIEW.md`, `./CLAUDE.md`, design docs cited).\n- For each file path mentioned in the plan, confirm the file exists (or is named as new in the plan). Missing files referenced as \"edit\" targets are a feasibility issue.\n- If the plan references prior work in commits or PRs, capture branch + base ref for the run metadata header.\n\nDo **not** read the entire codebase. Read only what the plan references plus enough to verify the named files exist.\n\n### 3. Apply the plan-shape contract\n\nThe plan must satisfy these structural rules. Any violation contributes to `NEEDS_REVISION` or `BLOCKED` per the verdict rules.\n\n| Rule | Severity if violated |\n|---|---|\n| Tasks are `- [ ]` checkboxes | BLOCKED — no machine-readable progress |\n| Each task names the files it touches | NEEDS_REVISION — implementer guesses scope |\n| Each task includes a **probable** verification step (greppable string, command with expected output, or file-content assertion — NOT \"section X present\" / \"file exists\") | NEEDS_REVISION — completion is unverifiable |\n| Tasks are sized 2-5 min (small) to ~30 min (max) | NEEDS_REVISION — too coarse to track or recover from failure |\n| Plan has a stated end-state (one paragraph or \"Definition of Done\") | NEEDS_REVISION — no exit criterion |\n| Plan has a \"Constraints\" or \"Out of scope\" section (or equivalent) | LOW — preferred but not required |\n\n### 4. Apply the content checklist\n\nReview the plan against the checklist in [reference.md](reference.md):\n- Feasibility\n- Completeness / gap\n- Open questions\n- Ordering\n- Verification\n- Scope creep\n- Risk / blast radius\n- Improvements\n\nFor each finding, cite the plan line (e.g. `PLAN.md:42`). When `pr_url` is provided (a plan being reviewed inside a PR), wrap line references via `~/.claude/scripts/pr-deeplink.sh \"$pr_url\" <plan-path> <line>` — same convention as siblings.\n\n### 5. Compute the verdict\n\nApply in order; first match wins:\n\n1. **BLOCKED** if any of:\n   - Plan does not resolve / is empty.\n   - Plan-shape contract: missing checkboxes (no `- [ ]` lines).\n   - A task references a file that doesn't exist and isn't created earlier in the plan.\n   - A task requires a decision the user has not made and the plan does not record (architecture choice, library choice, naming convention). The plan can't be executed without inventing.\n   - A task is destructive and lacks explicit user-confirmation gating (e.g. \"drop table\", \"delete prod data\", \"force push\").\n2. **NEEDS_REVISION** if any of:\n   - Two or more plan-shape contract NEEDS_REVISION rules violated.\n   - High-priority open questions that are answerable but not yet answered.\n   - Ordering bug: Task B depends on Task A but listed before A.\n   - Verification missing on more than ~30% of tasks.\n3. **READY** otherwise. Minor improvements may still be present; they are non-blocking.\n\n### 6. Present results\n\nResolve the review output directory (same pattern as sibling reviews):\n\n```sh\nREVIEW_DATE=$(date +%Y-%m-%d)\nREVIEW_DIR=\"reviews/${REVIEW_DATE}\"\nif [ -d \"$REVIEW_DIR\" ]; then REVIEW_DIR=\"reviews/${REVIEW_DATE}-$(date +%H%M)\"; fi\nmkdir -p \"$REVIEW_DIR\"\n```\n\nCapture run metadata (see [Run metadata header](#run-metadata-header)) and prepend to `${REVIEW_DIR}/PLAN-REVIEW.md`.\n\nOutput structure:\n1. Run metadata header\n2. **Verdict line** (first line after the H1): `**Verdict:** READY | NEEDS_REVISION | BLOCKED`\n3. One-sentence rationale for the verdict\n4. Findings table\n5. Recommended action: if `NEEDS_REVISION`, the minimal set of edits to the plan that would flip it to `READY`; if `BLOCKED`, the decision(s) the user must make before re-review.\n\nPresent the report. When invoked by `implement-plan`, return the verdict as the first machine-parseable line and stop.\n\n---\n\n## Invocation by other skills\n\nWhen `implement-plan` (or any other skill) invokes `review-plan` as a gate:\n\n- The plan path is supplied as an explicit argument.\n- The caller treats the returned verdict as authoritative:\n  - `READY` → proceed.\n  - `NEEDS_REVISION` → surface findings to the user, ask whether to revise or proceed anyway.\n  - `BLOCKED` → halt; surface findings; do not proceed even with user override (the plan literally cannot run).\n- The caller must not implementation-edit the plan to flip the verdict; revisions are a separate human step.\n\n---\n\n## Run metadata header\n\n```sh\nRUN_DATETIME=$(date -u +\"%Y-%m-%d %H:%M UTC\")\nGIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"(not a git repo)\")\nGIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo \"—\")\nGIT_COMMIT_FULL=$(git rev-parse HEAD 2>/dev/null || echo \"—\")\nGIT_SUBJECT=$(git log -1 --pretty=%s 2>/dev/null || echo \"—\")\nPLAN_PATH=<resolved plan file path>\n```\n\n```markdown\n> **Run:** {RUN_DATETIME}\n> **Branch:** {GIT_BRANCH} @ {GIT_COMMIT} (`{GIT_COMMIT_FULL}`)\n> **Subject:** {GIT_SUBJECT}\n> **Plan:** {PLAN_PATH}\n```\n\nNote: this skill runs fine outside a git repo. Fall back gracefully when git commands fail.\n\n---\n\n## Output Templates\n\n### Verdict block (always first, after H1)\n\n```markdown\n**Verdict:** READY\n\nPlan is structurally sound, all tasks have verification, no open questions. Minor improvements noted below.\n```\n\n```markdown\n**Verdict:** NEEDS_REVISION\n\nTwo tasks missing verification; one ordering bug (Task 4 references a file Task 6 creates). Plan recoverable with ~5 edits.\n```\n\n```markdown\n**Verdict:** BLOCKED\n\nTask 2 requires choosing between Redis and Memcached; the plan does not record this decision. Cannot proceed without user input.\n```\n\n### Findings table\n\n```markdown\n| Priority | Category | Finding | Recommendation | Plan line |\n|----------|----------|---------|----------------|-----------|\n| P0 | feasibility | Task 3 edits `internal/auth/jwt.go` but file does not exist and is not created earlier | Create the file in a preceding task or confirm path | PLAN.md:42 |\n| P1 | open-question | Task 5 says \"use the standard cache\" — repo has both `bigcache` and `ristretto` in use | Specify which; or escalate to user | PLAN.md:58 |\n| P2 | verification | Task 7 has no verification step | Add `task test ./internal/queue/...` with expected pass | PLAN.md:71 |\n| P3 | improvement | Tasks 2-4 are independent of Tasks 5-8; could split into two PRs | nit: only worth doing if PRs are getting large | PLAN.md:30-72 |\n```\n\n**Priority column values:** `P0` (blocker), `P1` (high), `P2` (medium), `P3` (low / nit).\n\n**Category column values:** `feasibility`, `gap`, `open-question`, `ordering`, `verification`, `scope`, `shape`, `risk`, `improvement`.\n\n**Plan line column:** Line reference into the reviewed plan file. When `pr_url` is set, wrap the reference via `~/.claude/scripts/pr-deeplink.sh \"$pr_url\" <plan-path> <line>`.\n\n### Recommended action\n\n```markdown\n## To move to READY\n\n1. Add a \"depends on Task 3\" annotation to Task 5 OR reorder so Task 5 precedes Task 3.\n2. Add verification step to Task 7: `task test ./internal/queue/... → PASS`.\n3. Pick a cache library in Task 5 (recommend `ristretto` per existing usage in `internal/...`).\n```\n\n```markdown\n## To unblock\n\nThe plan needs the following decisions before re-review:\n1. **Cache library**: Redis or Memcached for Task 2?\n2. **API versioning**: bump to `v2` or add additive field in `v1`?\n\nOnce decided, edit the plan to record the choice and request `review-plan` again.\n```\n\n---\n\n## Guidelines\n\n- The verdict is a gate, not a vote. Apply the rules; don't hedge to be polite.\n- A `READY` plan is not a *good* plan, only an *executable* one. Improvements stay as P3 findings and don't block.\n- Do not edit the plan during review. Surface findings; let the user (or plan-author) revise.\n- When `implement-plan` invokes this skill, return the verdict first so the caller can branch without parsing the whole report.\n- For detailed checklist categories, see [reference.md](reference.md).\n- This skill is **not** included in `review-all`. Plan review is plan-time; code review is code-time. Different lifecycle, different invocation.\n- Verification steps in tasks must be probable (run/grep/output), not presence-checks (\"section X present\" passes for anything). Per `~/.claude/rules/probe-not-assume.md`.","tags":["review","plan","skill","issue","paultyng","agent-skills","ai-tools","claude-code","cursor","dotfiles"],"capabilities":["skill","source-paultyng","skill-review-plan","topic-agent-skills","topic-ai-tools","topic-claude-code","topic-cursor","topic-dotfiles"],"categories":["skill-issue"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/paultyng/skill-issue/review-plan","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add paultyng/skill-issue","source_repo":"https://github.com/paultyng/skill-issue","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (9,004 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:09:02.794Z","embedding":null,"createdAt":"2026-05-18T13:21:27.814Z","updatedAt":"2026-05-18T19:09:02.794Z","lastSeenAt":"2026-05-18T19:09:02.794Z","tsv":"'-1':911 '-4':1108 '-5':355 '-72':1130 '-8':1114 '/.claude/rules/probe-not-assume.md':1408 '/.claude/scripts/pr-deeplink.sh':458,1176 '/claude.md':198 '/dev/null':879,894,905,915 '/docs/plans':157 '/internal/queue':1099,1214 '/plan-review.md':682 '/plan.md':146 '/review-plan':143 '/review.md':197 '1':129,136,475,685,1186,1244 '2':145,181,354,560,689,878,893,904,914,1007,1107,1205,1252,1253 '3':152,271,609,702,1038,1192,1204,1216 '30':359,606 '4':406,710,991 '5':465,713,1001,1067,1113,1196,1201,1223 '6':623,996 '7':1091,1211 'abbrev':875 'abbrev-ref':874 'action':715,1180 'add':1096,1187,1206,1260 'addit':1261 'alway':957 'analyz':105 'annot':1193 'anoth':39 'answer':584,588 'anyth':1406 'anyway':818 'api':1254 'appli':272,407,469,1289 'architectur':527 'argument':794 'artifact':115 'ask':8,172,812 'assert':339 'author':1334 'authorit':802 'b':592 'back':947 'base':244 'bigcach':1076 'blast':430 'block':75,292,304,476,622,701,734,819,956,1005,1318 'blocker':1135 'branch':243,869,923,925,1351 'bug':590,989 'bump':1256 'cach':1072,1219,1245 'caller':796,836,1349 'cannot':833,1021 'captur':242,666 'categori':1030,1143,1360 'check':15,29,127,1400 'checkbox':303,491 'checklist':410,416,1359 'choic':528,530,1273 'choos':1009 'cite':201,436 'coars':365 'code':101,1379,1383 'code-tim':1382 'codebas':119,256 'column':1132,1144,1159 'command':331,951 'commit':239,886,897,927,929 'complet':348,421 'comput':466 'confirm':210,550,1059 'constraint':393 'content':338,409 'context':124,183 'contract':277,489,572 'contribut':287 'convent':166,462,532 'could':1115 'creat':506,997,1049,1051 'creep':428 'criterion':389 'current':149 'd':642,649,864 'data':557 'date':638,639,647,657,658,860 'datetim':859,922 'dd':163 'decid':1266 'decis':515,736,1020,1239 'definit':382 'delet':555 'depend':593,1189 'design':199 'destruct':544 'detail':1358 'diff':107 'differ':1385,1387 'dir':644,651,654,665,681 'directori':151,630 'doc':192,200 'docs/plans/auth-rewrite.md':144 'document':97 'doesn':500 'done':384 'drop':553 'e.g':142,440,552 'earlier':507,1050 'echo':880,895,906,916 'edit':226,723,841,1002,1039,1267,1321 'empti':485 'end':377 'end-stat':376 'enough':264 'entir':255 'equival':400 'escal':1084 'evalu':21,50 'even':826 'execut':52,88,538,1308 'exist':213,270,345,502,1045,1227 'exit':388 'expect':333,1101 'explicit':137,547,793 'fail':952 'failur':371 'fall':946 'feasibl':28,126,230,420,1036,1146 'fi':661 'field':1262 'file':68,133,188,204,212,223,269,314,337,344,498,994,1042,1053,1166 'file-cont':336 'find':79,435,711,808,822,1026,1031,1314,1327 'fine':941 'first':472,692,760,958,1346 'flight':48,61 'flip':729,845 'follow':1238 'forc':558 'full':898,930 'fulli':189 'gap':422,1147 'gate':89,551,785,1285 'get':1127 'git':868,870,883,885,887,896,899,907,909,924,926,928,932,944,950 'good':1304 'grace':948 'greppabl':329 'guess':180,320 'guidelin':1280 'h':659,865 'h1':696,960 'halt':820 'head':877,892,903 'header':250,672,676,688,856 'hedg':1294 'high':578,1137 'high-prior':577 'human':852 'implement':43,65,92,319,753,773,840,1338 'implement-plan':42,91,752,772,1337 'implementation-edit':839 'improv':432,613,976,1105,1156,1310 'includ':324,1368 'independ':1110 'inlin':196 'input':1025 'insid':451 'intern':1230 'internal/auth/jwt.go':1040 'invent':540 'invoc':141,767,1388 'invok':750,779,1340 'isn':504 'issu':231 'lack':546 'larg':1128 'latest':153 'let':1328 'librari':529,1220,1246 'lifecycl':1386 'like':41 'line':439,455,493,691,693,764,1034,1158,1160 'list':598 'liter':832 'load':182 'log':910 'low':401,1141 'm':641,660,863,866 'machin':307,762 'machine-pars':761 'machine-read':306 'made':520 'make':741 'markdown':67,919,961,979,1003,1028,1181,1231 'match':473 'max':361 'may':614 'md':158,164 'medium':1139 'memcach':1013,1249 'mention':206 'metadata':249,668,671,675,687,855 'min':356,360 'minim':720 'minor':612,975 'miss':222,490,602,985 'mkdir':662 'mm':162 'move':1183 'mtime':155 'must':280,740,837,1393 'name':216,268,312,531 'need':73,289,317,346,362,385,561,573,699,717,805,981,1236 'new':218 'nit':1120,1142 'non':621 'non-block':620 'none':168 'note':937,977 'one':379,704,987,1309 'one-sent':703 'open':423,580,973,1064,1149 'open-quest':1063,1148 'order':135,425,471,589,988,1151 'otherwis':611 'output':334,629,683,953 'outsid':942 'overrid':829 'p':663 'p0':1035,1134 'p1':1062,1136 'p2':1088,1138 'p3':1104,1140,1313 'paragraph':380 'pars':873,890,902,1353 'parseabl':763 'pass':1102,1215,1404 'path':36,138,177,205,788,918,936,1060 'pattern':632 'per':165,293,1226,1407 'pick':1217 'plan':3,12,17,20,23,26,32,35,44,49,57,66,93,110,132,187,194,209,221,234,261,275,279,372,390,413,438,448,480,487,510,523,534,570,726,754,774,782,787,831,843,917,934,935,964,998,1015,1033,1157,1165,1235,1269,1278,1300,1305,1323,1333,1339,1373,1377 'plan-author':1332 'plan-shap':274,486,569 'plan-tim':1376 'plan.md:30':1129 'plan.md:42':441,1061 'plan.md:58':1087 'plan.md:71':1103 'plus':263 'polit':1297 'pr':443,453,459,1168,1177 'pre':47,60,87 'pre-execut':86 'pre-flight':46,59 'preced':1056,1202 'prefer':402 'prepend':678 'presenc':1399 'presence-check':1398 'present':343,617,624,746,1403 'pretti':912 'prior':236 'priorit':78 'prioriti':134,579,1029,1131 'probabl':326,1395 'proceed':804,817,825,1022 'prod':556 'produc':69 'progress':309 'provid':446 'prs':241,1119,1125 'push':559 'question':424,581,974,1065,1150 'radius':431 'rational':706 're':744,1242 're-review':743,1241 'read':122,184,190,253,257 'read-on':121 'readabl':308 'readi':27,72,610,698,732,803,963,1185,1299 'recommend':714,1032,1179,1224 'record':526,1018,1271 'recov':369 'recover':999 'redi':1011,1247 'ref':245,876 'refer':195,235,262,456,496,992,1161,1174 'referenc':224 'reference.md':418,419,1362,1363 'reorder':1198 'repo':884,945,1073 'report':748,1356 'request':45,1275 'requir':405,513,1008 'resolv':130,169,186,483,626 'result':625 'return':755,799,1343 'rev':872,889,901 'rev-pars':871,888,900 'review':2,10,34,58,62,98,102,411,450,628,635,637,643,645,646,650,653,655,656,664,680,745,781,1164,1243,1277,1325,1371,1374,1380 'review-al':1370 'review-plan':1,33,780,1276 'revis':74,290,318,347,363,386,562,574,700,718,806,815,848,982,1335 'risk':429,1155 'ristretto':1078,1225 'rule':284,296,297,575,1291 'run':248,667,670,674,686,834,854,858,920,921,940 'run-metadata-head':673 'run/grep/output':1396 'saniti':14 'sanity-check':13 'satisfi':281 'say':1068 'scope':108,321,397,427,1153 'section':341,398,1401 'see':669,1361 'sentenc':705 'separ':851 'set':721,1171 'sever':298 'sh':636,857 'shape':276,488,571,1154 'short':891 'sibl':464,634 'size':353 'skill':40,770,778,939,1342,1365 'skill-review-plan' 'small':357 'sound':967 'source-paultyng' 'specifi':1081 'split':1116 'standalon':82 'standard':1071 'state':375,378 'static':104 'stay':1311 'step':328,853,1095,1208,1390 'still':615 'stop':170,766 'string':330 'structur':283,684,966 'subject':908,931,933 'suppli':790 'surfac':807,821,1326 'tabl':80,554,712,1027 'target':227 'task':301,311,323,351,495,512,542,591,595,608,969,984,990,995,1006,1037,1057,1066,1090,1097,1106,1112,1191,1195,1200,1203,1210,1212,1222,1251,1392 'templat':954 'test':117,1098,1213 'time':1378,1384 'topic-agent-skills' 'topic-ai-tools' 'topic-claude-code' 'topic-cursor' 'topic-dotfiles' 'touch':316 'track':367 'treat':112,797 'two':566,983,1118 'typic':159 'u':861 'unblock':1233 'unverifi':350 'url':444,460,1169,1178 'usag':1228 'use':4,55,81,1069,1080 'user':7,174,517,549,739,811,828,1024,1086,1330 'user-confirm':548 'utc':867 'v1':1264 'v2':1258 'valu':1133,1145 'verdict':71,295,468,690,697,709,757,800,847,955,962,980,1004,1282,1345 'verif':327,426,601,971,986,1089,1094,1152,1207,1389 'verifi':266 'version':1255 'vet':18 'via':457,1175 'violat':286,300,576 'vote':1288 'w':56 'whether':813 'whole':1355 'win':474 'without':539,1023,1352 'work':150,237 'workflow':128 'worth':1122 'would':728 'wrap':454,1172 'x':342,1402 'y':640,862 'yet':587 'yyyi':161 'yyyy-mm-dd':160","prices":[{"id":"18282977-7aa4-4afe-92e8-435e1660e838","listingId":"5a592720-e760-4378-ae8c-99749c4fc14b","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"paultyng","category":"skill-issue","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:27.814Z"}],"sources":[{"listingId":"5a592720-e760-4378-ae8c-99749c4fc14b","source":"github","sourceId":"paultyng/skill-issue/review-plan","sourceUrl":"https://github.com/paultyng/skill-issue/tree/main/skills/review-plan","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:27.814Z","lastSeenAt":"2026-05-18T19:09:02.794Z"}],"details":{"listingId":"5a592720-e760-4378-ae8c-99749c4fc14b","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"paultyng","slug":"review-plan","github":{"repo":"paultyng/skill-issue","stars":8,"topics":["agent-skills","ai-tools","claude-code","cursor","dotfiles"],"license":"mit","html_url":"https://github.com/paultyng/skill-issue","pushed_at":"2026-05-18T18:26:54Z","description":"Personal Claude Code / Cursor agent skills, rules, and config","skill_md_sha":"934b2b85aa8c8d9935e7d061e31579ae546f0c9e","skill_md_path":"skills/review-plan/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/paultyng/skill-issue/tree/main/skills/review-plan"},"layout":"multi","source":"github","category":"skill-issue","frontmatter":{"name":"review-plan","description":"Use when the user asks to review the plan, sanity-check the plan, vet the plan, evaluate the plan, \"is this plan ready\", feasibility check on a plan, \"review-plan PATH\", or when another skill (like implement-plan) requests pre-flight plan evaluation before execution. Do NOT use when no plan file is in scope (the user is likely asking for a summary — use Read instead), nor when the user is asking about source code (use review-code), nor when the user wants documentation review (use review-documentation)."},"skills_sh_url":"https://skills.sh/paultyng/skill-issue/review-plan"},"updatedAt":"2026-05-18T19:09:02.794Z"}}