{"id":"1e3326d3-625d-44c9-b41e-f9c8e9f55e82","shortId":"mNgQZg","kind":"skill","title":"recipe-review","tagline":"Design Doc compliance and security validation with optional auto-fixes","description":"**Context**: Post-implementation quality assurance\n\n## Orchestrator Definition\n\n**Core Identity**: \"I am an orchestrator.\"\n\n**First Action**: Register Steps 1-11 using TaskCreate before any execution.\n\n## Execution Method\n\n- Compliance validation → performed by code-reviewer\n- Security validation → performed by security-reviewer\n- **Code-side fix path**: Fix implementation → task-executor; Quality checks → quality-fixer; Re-validation → code-reviewer / security-reviewer\n- **Design-side update path**: DD revision → technical-designer (update mode); DD review → document-reviewer; cross-DD consistency → design-sync (when multiple DDs exist); Re-validation → code-reviewer\n\nOrchestrator invokes sub-agents and passes structured JSON between them. The design-side path applies when the discrepancy reflects code that was correct but the Design Doc became stale, rather than code that violated the Design Doc.\n\nDesign Doc (uses most recent if omitted): $ARGUMENTS\n\n## Execution Flow\n\n### Step 1: Prerequisite Check\n```bash\n# Identify Design Doc\nls docs/design/*.md | grep -v template | tail -1\n\n# Check implementation files\ngit diff --name-only main...HEAD\n```\n\n### Step 2: Execute code-reviewer\nInvoke code-reviewer using Agent tool:\n- `subagent_type`: \"dev-workflows:code-reviewer\"\n- `description`: \"Code compliance review\"\n- `prompt`: \"Design Doc: [path]. Implementation files: [git diff file list]. Review mode: full. Validate Design Doc compliance and return structured JSON report.\"\n\n**Store output as**: `$STEP_2_OUTPUT`\n\n### Step 3: Execute security-reviewer\nInvoke security-reviewer using Agent tool:\n- `subagent_type`: \"dev-workflows:security-reviewer\"\n- `description`: \"Security review\"\n- `prompt`: \"Design Doc: [path]. Implementation files: [git diff file list]. Review security compliance.\"\n\n**Store output as**: `$STEP_3_OUTPUT`\n\n### Step 4: Verdict and Response\n\n**If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps.\n\n**Code compliance criteria (considering project stage)**:\n- Prototype: Pass at 70%+\n- Production: 90%+ recommended\n\n**Security criteria**:\n- `approved` or `approved_with_notes` → Pass\n- `needs_revision` → Fail\n\n**Report both results independently using subagent output fields only**:\n\nBefore presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal — do not include it in the user-facing prompt):\n\n| Finding pattern | Recommended route |\n|-----------------|-------------------|\n| `dd_violation` where the code intent matches the original requirement but the Design Doc captured a different design | `d` (Design-side update) |\n| `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) |\n| `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) |\n\nThen present to the user (label each finding with its recommended route, grouped by route):\n\n```\nCode Compliance: [complianceRate from code-reviewer]\n  Verdict: [verdict from code-reviewer]\n  Identifier Match Rate: [identifierMatchRate from code-reviewer]\n  Acceptance Criteria:\n  - [fulfilled] [item] (confidence: [high/medium/low])\n  - [partially_fulfilled] [item]: [gap] — [suggestion] [recommended: c | d]\n  - [unfulfilled] [item]: [gap] — [suggestion] [recommended: c | d]\n  Identifier Mismatches:\n  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] [recommended: c | d]\n  Quality Findings:\n  - [category] [location]: [description] — [rationale] [recommended: c]\n\nSecurity Review: [status from security-reviewer]\n  Findings by category:\n  - [confirmed_risk] [location]: [description] — [rationale] [recommended: c]\n  - [defense_gap] [location]: [description] — [rationale] [recommended: c]\n  - [hardening] [location]: [description] — [rationale] [recommended: c]\n  - [policy] [location]: [description] — [rationale] [recommended: c]\n  Notes: [notes from security-reviewer, if present]\n\nResolve discrepancies — confirm or override the recommended route per finding:\n  c) Code-side fix       — code violates Design Doc; modify code to match\n  d) Design-side update  — code is correct; Design Doc is stale, revise it\n  s) Skip                — accept current state without changes\n```\n\nUse AskUserQuestion. The default offer is **\"accept all recommended routes\"** — a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11.\n\n### Step 5: Execute Skill\n\nExecute Skill: documentation-criteria (for task file template)\n\n### Step 5d: Design-Side Update\n\nRun this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6.\n\n1. Invoke technical-designer in update mode using Agent tool:\n   - `subagent_type`: \"dev-workflows:technical-designer\"\n   - `description`: \"Design Doc update from review findings\"\n   - `prompt`: \"Update Design Doc at [path] in update mode. The implementation has diverged in the following ways that the team has decided to ratify in the design rather than in the code: [list of `d`-routed findings with codeLocation and designDocValue from $STEP_2_OUTPUT]. Reflect the current code behavior in the relevant sections and add a history entry.\"\n\n2. Invoke document-reviewer to verify the updated Design Doc:\n   - `subagent_type`: \"dev-workflows:document-reviewer\"\n   - `description`: \"Document review of updated Design Doc\"\n   - `prompt`: \"Review updated Design Doc at [path] for consistency and completeness.\"\n\n3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync:\n   - `subagent_type`: \"dev-workflows:design-sync\"\n   - `description`: \"Cross-DD consistency check\"\n   - `prompt`: \"source_design: [updated DD path]. Detect conflicts across all Design Docs after the update.\"\n   - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer for affected DDs.\n\n4. After Step 5d completes:\n   - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-8, proceed to Step 9 for re-validation\n   - If the user selected both `d` and `c` → re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings\n\n### Step 6: Create Task File\n\nCreate task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md`\nInclude both code compliance issues and security requiredFixes.\n\n### Step 7: Execute Fixes\n\nInvoke task-executor using Agent tool:\n- `subagent_type`: \"dev-workflows:task-executor\"\n- `description`: \"Execute review fixes\"\n- `prompt`: \"Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files).\"\n\n### Step 8: Quality Check\n\nInvoke quality-fixer using Agent tool:\n- `subagent_type`: \"dev-workflows:quality-fixer\"\n- `description`: \"Quality gate check\"\n- `prompt`: \"Confirm quality gate passage for fixed files.\"\n\n### Step 9: Re-validate code-reviewer\n\nInvoke code-reviewer using Agent tool:\n- `subagent_type`: \"dev-workflows:code-reviewer\"\n- `description`: \"Re-validate compliance\"\n- `prompt`: \"Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side).\"\n\n### Step 10: Re-validate security-reviewer\n\nInvoke security-reviewer using Agent tool (only if security fixes were applied):\n- `subagent_type`: \"dev-workflows:security-reviewer\"\n- `description`: \"Re-validate security\"\n- `prompt`: \"Re-validate security after fixes. Prior findings: $STEP_3_OUTPUT. Design Doc: [path]. Implementation files: [file list].\"\n\n### Step 11: Final Cleanup and Report\n\nDelete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs:\n\n- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists\n\nIf the file cannot be deleted (filesystem error), report the failure but do not block the final report.\n\nThen present the final report:\n\n```\nCode Compliance:\n  Initial: [X]%\n  Final: [Y]% (if fixes executed)\n\nSecurity Review:\n  Initial: [status]\n  Final: [status] (if fixes executed)\n  Notes: [notes from approved_with_notes, if any]\n\nRemaining issues:\n- [items requiring manual intervention]\n\nCleanup: review-fixes task file removed\n```\n\n## Auto-fixable Items (code-side path)\n- Simple unimplemented acceptance criteria\n- Error handling additions\n- Contract definition fixes\n- Function splitting (length/complexity improvements)\n- Security confirmed_risk and defense_gap fixes (input validation, auth checks, output encoding)\n\n## Non-fixable Items\n- Fundamental business logic changes\n- Architecture-level modifications\n- Committed secrets (blocked → human intervention)\n\n## Design-Side Update Triggers\nDiscrepancies suitable for the design-side path (code is correct, DD became stale):\n- Identifier renames where the new identifier reflects the team's current naming\n- Behavioral changes that match the original requirement intent better than what the DD captured\n- Component splits or merges where the new structure is sound and the DD documented the prior structure\n- New ACs that the implementation already satisfies but the DD never enumerated\n\n**Scope**: Design Doc compliance validation, security review, code-side auto-fixes, and design-side update routing.\n\n## Scope Boundary for Subagents\n\nAppend the following block to every subagent prompt invoked from this recipe:\n\n```\nScope boundary for subagents:\nOperate within the review scope and referenced files in the prompt.\nUse loaded skills to execute that scope.\nEscalate when the required fix or investigation falls outside that scope.\n```","tags":["recipe","review","claude","code","workflows","shinpr","agent-skills","agentic-ai","ai-agents","automation","claude-code","claude-code-plugin"],"capabilities":["skill","source-shinpr","skill-recipe-review","topic-agent-skills","topic-agentic-ai","topic-ai-agents","topic-automation","topic-claude-code","topic-claude-code-plugin","topic-code-quality","topic-developer-tools","topic-development-workflow","topic-llm-orchestration","topic-productivity","topic-prompt-engineering"],"categories":["claude-code-workflows"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/shinpr/claude-code-workflows/recipe-review","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add shinpr/claude-code-workflows","source_repo":"https://github.com/shinpr/claude-code-workflows","install_from":"skills.sh"}},"qualityScore":"0.613","qualityRationale":"deterministic score 0.61 from registry signals: · indexed on github topic:agent-skills · 327 github stars · SKILL.md body (9,934 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-02T18:53:53.047Z","embedding":null,"createdAt":"2026-04-18T22:03:15.970Z","updatedAt":"2026-05-02T18:53:53.047Z","lastSeenAt":"2026-05-02T18:53:53.047Z","tsv":"'-1':178 '-10':642 '-11':34 '-8':902 '1':33,164,692,828 '10':1093 '11':646,1146 '2':190,240,761,777,1075 '3':243,283,814,1136 '4':286,883 '5':641,648,1001 '5d':661,886 '6':691,901,945,952 '7':970 '70':321 '8':1004 '9':906,1035 '90':323 'ac':1361 'accept':466,590,601,1256 'across':855 'action':30 'add':773 'addit':1260 'affect':881 'agent':118,200,253,701,978,1012,1047,1105 'alreadi':1365 'append':1395 'appli':130,996,1112 'approv':327,329,1228 'architectur':1290 'architecture-level':1289 'argument':160 'askuserquest':596 'assur':20 'auth':1277 'auto':13,1247,1383 'auto-fix':12,1246,1382 'bash':167 'becam':143,1315 'behavior':767,1329 'better':1337 'block':295,300,1198,1295,1398 'boundari':1392,1408 'busi':1286 'c':416,425,478,485,497,506,523,530,536,542,561,684,897,918,923,949 'c/d/s':629 'cannot':1187 'captur':394,1342 'case':611 'categori':501,516 'chang':594,1288,1330 'check':67,166,179,846,1006,1025,1278 'cleanup':1148,1239 'code':47,57,75,112,135,147,193,197,208,211,312,384,407,418,427,445,450,456,464,492,563,566,571,579,749,766,963,1040,1044,1055,1086,1207,1251,1311,1380 'code-review':46,74,111,192,196,207,449,455,463,1039,1043,1054 'code-sid':56,417,426,562,1085,1250,1379 'codeloc':756 'codevalu':493 'collect':625 'commit':1166,1293 'complet':813,887 'complianc':6,42,212,230,278,313,446,964,1061,1068,1072,1208,1375 'compliancer':447 'compon':1343 'comput':352 'confid':470 'confirm':517,553,607,1027,1269 'conflict':854,865,868 'consid':315 'consist':100,811,845 'context':15 'contract':1261 'core':23 'correct':138,413,581,618,1313 'creat':953,956,1160 'criteria':314,326,467,655,1257 'cross':98,843 'cross-dd':97,842 'current':591,765,1327 'd':398,479,486,498,574,679,752,892,916 'dd':85,92,99,380,403,490,844,851,929,939,1314,1341,1355,1369 'dds':106,882 'decid':739 'decis':630 'default':598 'defens':524,1272 'definit':22,1262 'delet':1151,1179,1189 'descript':210,263,503,520,527,533,539,711,796,841,988,1022,1057,1121 'design':4,81,89,102,127,141,151,153,169,215,228,267,392,397,400,414,568,576,582,663,696,710,712,720,744,786,801,806,817,831,839,849,857,879,1066,1090,1138,1299,1308,1373,1387 'design-sid':80,126,399,575,662,1089,1298,1307,1386 'design-sync':101,830,838 'designdocvalu':491,758 'detect':853 'dev':205,258,706,791,836,983,1017,1052,1116 'dev-workflow':204,257,705,790,835,982,1016,1051,1115 'diff':183,221,273 'differ':396 'direct':688 'discrep':133,552,1303 'diverg':730 'doc':5,142,152,154,170,216,229,268,393,415,569,583,713,721,787,802,807,818,858,1067,1139,1374 'docs/design':172,821 'docs/plans':1167 'docs/plans/tasks/review-fixes-yyyymmdd.md':960,995,1180 'document':95,654,780,794,797,1356 'document-review':94,779,793 'documentation-criteria':653 'drift':408 'drop':931 'encod':1280 'entri':776 'enumer':1371 'ephemer':1169 'error':1191,1258 'escal':303,1429 'evalu':921 'everi':1400 'everyth':638 'execut':39,40,161,191,244,649,651,971,989,1215,1224,1426 'executor':65,976,987 'exist':107,819,1183 'face':374 'fail':335 'failur':1194 'fall':1436 'field':343 'file':181,219,222,271,274,658,955,958,994,1002,1033,1142,1143,1157,1186,1244,1418 'filesystem':1190 'final':1147,1200,1205,1211,1220 'find':301,357,376,424,437,500,514,560,628,677,717,754,895,925,950,1134 'first':29 'fix':14,59,61,310,420,429,565,972,991,998,1032,1070,1110,1132,1155,1214,1223,1242,1263,1274,1384,1433 'fixabl':1248,1283 'fixer':70,1010,1021 'flow':162 'follow':733,1397 'found':866 'fulfil':468,473 'full':226 'function':1264 'fundament':1285 'gap':475,482,525,1273 'gate':1024,1029 'git':182,220,272 'grep':174,823 'group':442 'handl':1259 'harden':531 'head':188 'high/medium/low':471 'histori':775 'human':1296 'ident':24 'identifi':168,458,487,489,1317,1322 'identifiermatchr':461 'immedi':297 'implement':18,62,180,218,270,728,1141,1364 'improv':1267 'includ':368,961 'independ':339 'initi':1209,1218 'input':1275 'instead':631 'intent':385,1336 'intern':365 'intervent':1238,1297 'investig':1435 'invok':115,195,248,693,778,829,876,973,1007,1042,1100,1403 'issu':965,1073,1080,1234 'item':469,474,481,1235,1249,1284 'json':122,234 'l':827 'label':435 'least':675 'length/complexity':1266 'level':1291 'list':223,275,750,1144 'load':1423 'locat':495,502,519,526,532,538 'logic':1287 'ls':171,820 'main':187 'maintain':423 'manual':1237 'match':386,459,573,1332 'md':173,822 'merg':1346 'method':41 'mismatch':488 'mode':91,225,699,726 'modif':1292 'modifi':570 'multipl':105,816 'name':185,1328 'name-on':184 'need':333 'never':1370 'new':1321,1349,1360 'non':1282 'non-fix':1281 'note':331,543,544,1225,1226,1230 'offer':599 'omit':159 'one':676 'oper':1411 'option':11 'orchestr':21,28,114,351,614 'origin':388,1334 'output':237,241,280,284,342,762,1076,1137,1279 'outsid':1437 'overrid':555,624 'partial':472 'pass':120,319,332 'passag':1030 'path':60,84,129,217,269,723,809,852,1140,1253,1310 'pattern':377 'per':356,559,627 'per-find':626 'perform':44,51 'polici':537 'post':17 'post-implement':16 'prerequisit':165 'present':346,431,550,867,1203 'prior':1071,1079,1133,1358 'proceed':308,643,903,942 'product':322 'project':316 'prompt':214,266,375,718,803,847,992,1026,1062,1126,1402,1421 'prototyp':318 'qualiti':19,66,69,499,1005,1009,1020,1023,1028 'quality-fix':68,1008,1019 'rate':460 'rather':145,745 'ratifi':741 'rational':504,521,528,534,540 're':72,109,875,909,920,1037,1059,1064,1095,1123,1128 're-evalu':919 're-invok':874 're-valid':71,108,908,1036,1058,1063,1094,1122,1127 'recent':157 'recip':2,1159,1177,1406 'recipe-review':1 'recommend':324,354,378,440,477,484,496,505,522,529,535,541,557,603,616 'referenc':1417 'reflect':134,763,1323 'regist':31 'relev':770 'reliabl':421 'remain':948,1233 'remov':1245 'renam':1318 'report':235,298,336,1150,1192,1201,1206 'requir':389,873,1236,1335,1432 'requiredfix':968 'resolut':872 'resolv':551,1082,1084 'respons':289 'result':338 'retain':1175 'return':232,294 'review':3,48,55,76,79,93,96,113,194,198,209,213,224,247,251,262,265,276,293,451,457,465,508,513,548,716,781,795,798,804,990,1041,1045,1056,1099,1103,1120,1154,1217,1241,1378,1414 'review-fix':1153,1240 'revis':86,334,586,940 'risk':518,1270 'rout':355,379,441,444,558,604,673,682,753,898,924,1390 'rule':360,363 'run':666,1178 'satisfi':936,1366 'scope':1372,1391,1407,1415,1428,1439 'secret':1294 'section':771 'secur':8,49,54,78,246,250,261,264,277,292,325,422,507,512,547,967,1098,1102,1109,1119,1125,1130,1216,1268,1377 'security-review':53,77,245,249,260,291,511,546,1097,1101,1118 'select':635,891,914 'side':58,82,128,401,419,428,564,577,664,1087,1091,1252,1300,1309,1381,1388 'simpl':1254 'singl':606 'skill':650,652,1424 'skill-recipe-review' 'skip':589,639,687,899 'sound':1352 'sourc':848 'source-shinpr' 'split':1265,1344 'stage':317,997 'stale':144,585,1316 'state':592,1171 'status':509,864,1219,1221 'step':32,163,189,239,242,282,285,311,640,645,647,660,668,690,760,885,900,905,944,951,969,1003,1034,1074,1092,1135,1145 'still':412 'still-correct':411 'stop':296,999 'store':236,279 'structur':121,233,1350,1359 'sub':117 'sub-ag':116 'subag':202,255,341,703,788,833,980,1014,1049,1113,1394,1401,1410 'suggest':476,483 'suitabl':1304 'sync':103,832,840,863 'tail':177 'task':64,657,954,957,975,986,993,1156,1243 'task-executor':63,974,985 'taskcreat':36 'team':737,1325 'technic':88,695,709,878 'technical-design':87,694,708,877 'templat':176,659,825 'tool':201,254,702,979,1013,1048,1106 'topic-agent-skills' 'topic-agentic-ai' 'topic-ai-agents' 'topic-automation' 'topic-claude-code' 'topic-claude-code-plugin' 'topic-code-quality' 'topic-developer-tools' 'topic-development-workflow' 'topic-llm-orchestration' 'topic-productivity' 'topic-prompt-engineering' 'trigger':1302 'type':203,256,704,789,834,981,1015,1050,1114 'typic':610 'unfulfil':480 'unimpl':1255 'updat':83,90,402,578,665,698,714,719,725,785,800,805,850,861,928,1301,1389 'use':35,155,199,252,340,358,595,700,977,1011,1046,1104,1422 'user':305,349,373,434,621,634,672,871,890,913 'user-fac':372 'v':175,824 'valid':9,43,50,73,110,227,910,1038,1060,1065,1096,1124,1129,1276,1376 'verdict':287,452,453 'verifi':783,1077 'violat':149,381,404,567 'want':622 'way':734 'wc':826 'whether':1083 'within':1412 'without':593 'work':1164,1170 'workflow':206,259,707,792,837,984,1018,1053,1117 'x':1210 'y':1212","prices":[{"id":"5ff5cc49-4b64-4920-97ef-08fa2a0fcaa9","listingId":"1e3326d3-625d-44c9-b41e-f9c8e9f55e82","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"shinpr","category":"claude-code-workflows","install_from":"skills.sh"},"createdAt":"2026-04-18T22:03:15.970Z"}],"sources":[{"listingId":"1e3326d3-625d-44c9-b41e-f9c8e9f55e82","source":"github","sourceId":"shinpr/claude-code-workflows/recipe-review","sourceUrl":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/recipe-review","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:15.970Z","lastSeenAt":"2026-05-02T18:53:53.047Z"}],"details":{"listingId":"1e3326d3-625d-44c9-b41e-f9c8e9f55e82","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"shinpr","slug":"recipe-review","github":{"repo":"shinpr/claude-code-workflows","stars":327,"topics":["agent-skills","agentic-ai","ai-agents","automation","claude-code","claude-code-plugin","code-quality","developer-tools","development-workflow","llm-orchestration","productivity","prompt-engineering","skills"],"license":"mit","html_url":"https://github.com/shinpr/claude-code-workflows","pushed_at":"2026-05-02T15:39:17Z","description":"Production-ready development workflows for Claude Code, powered by specialized AI agents.","skill_md_sha":"1ef961c09ce305d042e4829d3dc00c1b7ccb29bf","skill_md_path":"skills/recipe-review/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/recipe-review"},"layout":"multi","source":"github","category":"claude-code-workflows","frontmatter":{"name":"recipe-review","description":"Design Doc compliance and security validation with optional auto-fixes"},"skills_sh_url":"https://skills.sh/shinpr/claude-code-workflows/recipe-review"},"updatedAt":"2026-05-02T18:53:53.047Z"}}