{"id":"cefa0457-77ca-49b8-85e8-e4afd3a82f4e","shortId":"tFzjVu","kind":"skill","title":"document-review","tagline":">-","description":"# Document Review\n\nImprove brainstorm or plan documents through structured review.\n\n## Step 1: Get the Document\n\n**If a document path is provided:** Read it, then proceed to Step 2.\n\n**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.\n\n## Step 2: Assess\n\nRead through the document and ask:\n\n- What is unclear?\n- What is unnecessary?\n- What decision is being avoided?\n- What assumptions are unstated?\n- Where could scope accidentally expand?\n- Is this technically feasible with the current architecture?\n- Are there security implications in what's proposed?\n\nThese questions surface issues. Don't fix yet--just note what you find.\n\n## Step 3: Activate Review Lenses\n\nBased on the document's content, activate specialized review perspectives. Scan for signals and apply matching lenses:\n\n| Lens | Signals | What it checks |\n|------|---------|----------------|\n| **Product** | User-facing features, customer language, market claims, scope decisions | Problem framing, value proposition clarity, whether scope matches stated goals |\n| **Design** | UI/UX references, user flows, wireframes, interaction descriptions | Flow completeness, interaction gaps, accessibility considerations |\n| **Security** | Auth/authorization, API endpoints, PII, payments, tokens, encryption | Auth model gaps, data exposure risks, missing threat considerations |\n| **Scope guardian** | Multiple priority tiers (P0/P1/P2), large requirement count (>8), stretch goals | Scope creep, premature abstractions, features disguised as requirements |\n| **Adversarial** | >5 distinct requirements, explicit architectural decisions, high-stakes domains | Unstated assumptions, optimistic estimates, single points of failure, missing failure modes |\n\nActivate a lens when ANY of its signals match. Most documents trigger 1-2 lenses; brainstorm notes may trigger none. When a lens is active, weave its checks into the assessment and evaluation steps rather than running it as a separate pass.\n\n## Step 4: Evaluate\n\nScore the document against these criteria:\n\n| Criterion | What to Check |\n|-----------|---------------|\n| **Clarity** | Problem statement is clear, no vague language (\"probably,\" \"consider,\" \"try to\") |\n| **Completeness** | Required sections present, constraints stated, open questions flagged |\n| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |\n| **YAGNI** | No hypothetical features, simplest approach chosen |\n\nIf invoked within a workflow (after `/ia-brainstorm` or `/ia-plan`), also check:\n- **User intent fidelity** -- Document reflects what was discussed, assumptions validated\n\n## Step 5: Identify the Critical Improvement\n\nAmong everything found in Steps 2-4, does one issue stand out? If something would significantly improve the document's quality, this is the \"must address\" item. Highlight it prominently.\n\n## Step 6: Make Changes\n\nPresent your findings, then:\n\n1. **Auto-fix** minor issues (vague language, formatting) without asking\n2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)\n3. **Update** the document inline--no separate files, no metadata sections\n\n### Simplification Guidance\n\nSimplification is purposeful removal of unnecessary complexity, not shortening for its own sake.\n\n**Simplify when:**\n- Content serves hypothetical future needs, not current ones\n- Sections repeat information already covered elsewhere\n- Detail exceeds what's needed to take the next step\n- Abstractions or structure add overhead without clarity\n\n**Don't simplify:**\n- Constraints or edge cases that affect implementation\n- Rationale that explains why alternatives were rejected\n- Open questions that need resolution\n\n## Step 7: Reader Test (Optional)\n\nFor standalone documents that must be self-contained (onboarding guides, ADRs, external-facing docs), dispatch a zero-context sub-agent to simulate a first-time reader. The sub-agent has no conversation history — it sees only what a future reader would see.\n\n**How to run the test:**\n\n1. **Predict 5-10 reader questions** from the document's stated goals — one per major section or decision. Mix three kinds:\n   - Concrete retrieval: \"What command sets up the dev environment?\"\n   - Decision rationale: \"Why did we pick X over Y?\"\n   - Ambiguity probe: \"Could a reader interpret <specific phrase> in more than one way?\"\n2. **Dispatch a fresh sub-agent** with the document attached and the questions. No prior context, no session history.\n3. **Compare the sub-agent's answers** against author intent. Also ask the sub-agent directly: \"What feels ambiguous? What prior knowledge does this assume? Are there internal contradictions?\"\n\n**Interpret results:**\n\n- Correct, confident answers → document is self-contained for that question.\n- Wrong answer with high confidence → document actively misleads. Highest-priority fix.\n- Hedged or \"insufficient information\" → the document has a gap the author didn't notice. Fill it.\n- Sub-agent flags ambiguity the author didn't intend → reword for precision.\n\nSkip for context-dependent docs (brainstorm notes, plan files, internal working docs) where the reader will always have prior context. The sub-agent test only adds value when the real reader has no other channel.\n\n## Step 8: Offer Next Action\n\nAfter changes are complete, ask:\n\n1. **Refine again** - Another review pass\n2. **Review complete** - Document is ready\n\n### Iteration Guidance\n\nAfter 2 refinement passes, recommend completion--diminishing returns are likely. If the user wants to continue, allow up to 4 passes total. After 4, stop and report \"review converged -- further changes require new direction.\" Do not continue past 4 even on user request without a fresh framing.\n\nReturn control to the caller (workflow or user) after selection.\n\n## Constraints\n\n- Fix targeted sections, don't rewrite the whole document. If the structure is fundamentally broken, surface the structural problem and ask for permission to restructure.\n- Flag missing sections in your review, but don't add them. The user decides what to include.\n- Keep changes minimal. If a paragraph needs tightening, tighten it. Don't expand scope.\n- Review inline. No separate review files or metadata sections.\n\n## Success Criteria\n\n- Document read and scored on all four quality criteria\n- Relevant review lenses activated and checks applied\n- Critical improvements identified with specific suggestions\n- User presented with clear next-action choice (refine or complete)\n- Revised document saved if changes were approved","tags":["document","review","skills","iliaal","agent-skills","ai-coding-assistant","ai-tools","claude-code"],"capabilities":["skill","source-iliaal","skill-document-review","topic-agent-skills","topic-ai-coding-assistant","topic-ai-tools","topic-claude-code","topic-skills"],"categories":["ai-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/iliaal/ai-skills/document-review","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add iliaal/ai-skills","source_repo":"https://github.com/iliaal/ai-skills","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 13 github stars · SKILL.md body (6,618 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:07:01.990Z","embedding":null,"createdAt":"2026-05-09T01:05:35.003Z","updatedAt":"2026-05-18T19:07:01.990Z","lastSeenAt":"2026-05-18T19:07:01.990Z","tsv":"'-10':556 '-2':245 '-4':360 '/ia-brainstorm':333 '/ia-plan':335 '1':15,244,392,553,755 '2':31,54,359,403,603,761,770 '3':112,414,623 '4':275,788,792,807 '5':211,349,555 '6':385 '7':496 '8':199,746 'abstract':205,466 'access':171 'accident':80 'action':749,922 'activ':113,122,232,256,673,906 'add':469,735,861 'address':379 'adr':511 'adversari':210 'affect':481 'agent':523,534,609,628,639,697,732 'allow':785 'alreadi':453 'also':336,634 'altern':487 'alway':725 'ambigu':592,643,699 'among':354 'anoth':758 'answer':630,658,668 'api':175 'appli':130,909 'approach':325 'approv':405,933 'architectur':89,215 'ask':37,61,402,404,635,754,847 'assess':55,262 'assum':649 'assumpt':74,222,346 'attach':613 'auth':181 'auth/authorization':174 'author':632,689,701 'auto':394 'auto-fix':393 'avoid':72 'base':116 'brainstorm':7,247,314,714 'brainstorm/plan':48 'broken':841 'caller':820 'case':479 'chang':387,408,412,751,799,870,931 'channel':744 'check':137,259,286,337,908 'choic':923 'chosen':326 'claim':146 'clariti':153,287,472 'clear':291,919 'command':577 'compar':624 'complet':168,299,753,763,774,926 'complex':433 'concret':309,574 'confid':657,671 'consid':296 'consider':172,189 'constraint':303,476,826 'contain':508,663 'content':121,442 'context':520,619,711,728 'context-depend':710 'continu':784,805 'contradict':653 'control':817 'converg':797 'convers':537 'correct':656 'could':78,594 'count':198 'cover':454 'creep':203 'criteria':282,893,902 'criterion':283 'critic':352,910 'current':88,448 'custom':143 'data':184 'decid':865 'decis':69,148,216,570,583 'depend':712 'descript':166 'design':159 'detail':456 'dev':581 'didn':690,702 'diminish':775 'direct':640,802 'discuss':345 'disguis':207 'dispatch':516,604 'distinct':212 'doc':515,713,720 'docs/brainstorms':50 'docs/plans':52 'document':2,4,10,18,21,34,39,59,119,242,279,341,372,417,502,561,612,659,672,684,764,835,894,928 'document-review':1 'domain':220 'edg':478 'elsewher':455 'encrypt':180 'endpoint':176 'enough':310 'environ':582 'estim':224 'evalu':264,276 'even':808 'everyth':355 'exceed':457 'expand':81,881 'explain':485 'explicit':214 'exposur':185 'extern':513 'external-fac':512 'face':141,514 'failur':228,230 'feasibl':85 'featur':142,206,323 'feel':642 'fidel':340 'file':421,717,888 'fill':693 'find':110,390 'first':528 'first-tim':527 'fix':104,395,678,827 'flag':307,698,852 'flow':163,167 'format':400 'found':356 'four':900 'frame':150,815 'fresh':606,814 'fundament':840 'futur':445,544 'gap':170,183,687 'get':16 'goal':158,201,564 'guardian':191 'guid':510 'guidanc':426,768 'hedg':679 'high':218,670 'high-stak':217 'highest':676 'highest-prior':675 'highlight':381 'histori':538,622 'hypothet':322,444 'identifi':350,912 'implement':319,482 'implic':93 'improv':6,353,370,911 'includ':868 'inform':452,682 'inlin':418,884 'insuffici':681 'intend':704 'intent':339,633 'interact':165,169 'intern':652,718 'interpret':597,654 'invok':328 'issu':101,363,397 'item':380 'iter':767 'keep':869 'kind':573 'knowledg':646 'languag':144,294,399 'larg':196 'len':133,234,254 'lens':115,132,246,905 'like':778 'look':43 'major':567 'make':386 'market':145 'match':131,156,240 'may':249 'mean':413 'metadata':423,890 'minim':871 'minor':396 'mislead':674 'miss':187,229,853 'mix':571 'mode':231 'model':182 'multipl':192 'must':378,504 'need':446,460,493,875 'new':801 'next':312,464,748,921 'next-act':920 'none':251 'note':107,248,715 'notic':692 'offer':747 'onboard':509 'one':362,449,565,601 'open':305,490 'optimist':223 'option':499 'overhead':470 'p0/p1/p2':195 'paragraph':874 'pass':273,760,772,789 'past':806 'path':22 'payment':178 'per':566 'permiss':849 'perspect':125 'pick':588 'pii':177 'plan':9,316,317,716 'point':226 'precis':707 'predict':554 'prematur':204 'present':302,388,917 'prior':618,645,727 'prioriti':193,677 'probabl':295 'probe':593 'problem':149,288,845 'proceed':28 'product':138 'promin':383 'propos':97 'proposit':152 'provid':24 'purpos':429 'qualiti':374,901 'question':99,306,491,558,616,666 'rather':266 'rational':483,584 'read':25,56,895 'reader':497,530,545,557,596,723,740 'readi':766 'real':739 'recent':47 'recommend':773 'refer':161 'refin':756,771,924 'reflect':342 'reject':489 'relev':903 'remov':410,430 'repeat':451 'report':795 'request':811 'requir':197,209,213,300,800 'resolut':494 'restructur':409,851 'result':655 'retriev':575 'return':776,816 'review':3,5,13,41,114,124,759,762,796,857,883,887,904 'revis':927 'reword':705 'rewrit':832 'risk':186 'run':268,550 'sake':439 'save':929 'scan':126 'scope':79,147,155,190,202,882 'score':277,897 'section':301,411,424,450,568,829,854,891 'secur':92,173 'see':540,547 'select':825 'self':507,662 'self-contain':506,661 'separ':272,420,886 'serv':443 'session':621 'set':578 'shorten':435 'signal':128,134,239 'signific':369 'simplest':324 'simplif':425,427 'simplifi':440,475 'simul':525 'singl':225 'skill' 'skill-document-review' 'skip':708 'someth':367 'source-iliaal' 'special':123 'specif':308,914 'specifi':36 'stake':219 'stand':364 'standalon':501 'state':157,304,563 'statement':289 'step':14,30,53,111,265,274,313,348,358,384,465,495,745 'stop':793 'stretch':200 'structur':12,468,838,844 'sub':522,533,608,627,638,696,731 'sub-ag':521,532,607,626,637,695,730 'substant':407 'success':892 'suggest':915 'surfac':100,842 'take':462 'target':828 'technic':84 'test':498,552,733 'threat':188 'three':572 'tier':194 'tighten':876,877 'time':529 'token':179 'topic-agent-skills' 'topic-ai-coding-assistant' 'topic-ai-tools' 'topic-claude-code' 'topic-skills' 'total':790 'tri':297 'trigger':243,250 'ui/ux':160 'unclear':64 'unnecessari':67,432 'unstat':76,221 'updat':415 'user':140,162,338,781,810,823,864,916 'user-fac':139 'vagu':293,398 'valid':347 'valu':151,736 'want':782 'way':602 'weav':257 'whether':154 'whole':834 'wirefram':164 'within':329 'without':401,471,812 'work':719 'workflow':331,821 'would':368,546 'wrong':667 'x':589 'y':591 'yagni':320 'yet':105 'zero':519 'zero-context':518","prices":[{"id":"091d749a-df98-43e1-8e7e-d6cae840defa","listingId":"cefa0457-77ca-49b8-85e8-e4afd3a82f4e","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"iliaal","category":"ai-skills","install_from":"skills.sh"},"createdAt":"2026-05-09T01:05:35.003Z"}],"sources":[{"listingId":"cefa0457-77ca-49b8-85e8-e4afd3a82f4e","source":"github","sourceId":"iliaal/ai-skills/document-review","sourceUrl":"https://github.com/iliaal/ai-skills/tree/master/skills/document-review","isPrimary":false,"firstSeenAt":"2026-05-09T01:05:35.003Z","lastSeenAt":"2026-05-18T19:07:01.990Z"}],"details":{"listingId":"cefa0457-77ca-49b8-85e8-e4afd3a82f4e","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"iliaal","slug":"document-review","github":{"repo":"iliaal/ai-skills","stars":13,"topics":["agent-skills","ai-coding-assistant","ai-tools","claude-code","skills"],"license":"mit","html_url":"https://github.com/iliaal/ai-skills","pushed_at":"2026-05-16T13:15:17Z","description":"Curated collection of agent skills for AI coding assistants.","skill_md_sha":"eaecc3807bb44305663403dbe634a43eecb37f75","skill_md_path":"skills/document-review/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/iliaal/ai-skills/tree/master/skills/document-review"},"layout":"multi","source":"github","category":"ai-skills","frontmatter":{"name":"document-review","description":">-"},"skills_sh_url":"https://skills.sh/iliaal/ai-skills/document-review"},"updatedAt":"2026-05-18T19:07:01.990Z"}}