[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DBKSQF24E7HD7EEVB949F3":3,"skill-same:01M7DBKSQF24E7HD7EEVB949F3":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7DBKSQF24E7HD7EEVB949F3","gist-doc-review",null,"Review the comments and doc strings in a change — cut the ones restating the code, shorten the bloated ones, add the missing line on public API. Use when asked to \"review the docs\", \"check my comments\", \"am I overdocumenting\", \"doc review\", or before shipping a change that added a lot of prose.","msurkovsky\u002Fgist","msurkovsky","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F618135?v=4","01M7DBFZY3C5C90611RG7ZJJAG","Martin Šurkovský","01M7DBFZYQC296ZH4GJTJ54565",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fskills\u002Fgist-doc-review\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: gist-doc-review\ndescription: Review the comments and doc strings in a change — cut the ones restating the code, shorten the bloated ones, add the missing line on public API. Use when asked to \"review the docs\", \"check my comments\", \"am I overdocumenting\", \"doc review\", or before shipping a change that added a lot of prose.\n---\n\n# Doc review\n\n## The rules\n\n1. **Brief and easy to follow.**\n2. **Only non-obvious behaviour.** If the code says it, leave it out.\n3. **Clear private helpers need no comment at all.**\n4. **Every public function, type and exported const gets at least a brief line**,\n   so it is described wherever the docs are read.\n\nRules 1–3 delete. Rule 4 adds. Most changes need both directions at once —\na change with too much prose in the internals and none on its public surface\nis the normal case, not the exception.\n\n## Procedure\n\n**1. Measure.**\n\n```bash\ngk doc --base main --json     # what this branch added\ngk doc --json                 # uncommitted, including new files\ngk doc --range A..B --json\n```\n\nRead `totals.ratio`, `files[]`, and `runs[]` (comment blocks ≥2 lines, longest\nfirst). One-line asides are excluded by default — that is the point.\nIf the tool or repository is unavailable, identify the missing measurement.\nContinue from a supplied diff when sufficient; never invent a ratio or install\ntools as a side effect of review. When `gk` is missing, give the user its\ninstall command:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf \\\n  https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Freleases\u002Flatest\u002Fdownload\u002Fgist-cli-installer.sh | sh\n```\n\n**2. Triage with the runs, not the ratio.**\n\nRead every run of 4+ lines. Spot-check two or three shorter ones. The runs list\nis sorted longest-first because length is the cheapest signal of a rule 1 or\nrule 2 violation.\n\n**3. Judge each comment, in this order.**\n\n| Ask | If yes |\n|---|---|\n| Does the code below already say this? | **cut** |\n| Is it a private helper with a clear name and signature? | **cut** |\n| Is it three sentences where one would do? | **shorten** |\n| Does it explain *why*, a constraint, or a consequence? | **keep** |\n\n**4. Check the other direction.**\n\nFind public items in the change with no doc line at all. Per-language patterns:\n[references\u002Fpublic-surface.md](references\u002Fpublic-surface.md). Every one of them is a rule 4 finding.\n\n**5. Report.** Do not edit yet. Findings first, fixes when asked.\n\n## Keep vs cut\n\n**Keep** — the reader cannot get this from the code:\n- why this approach and not the obvious one\n- a constraint imposed from somewhere else: a wire format, an ordering another\n  file asserts, a caller that breaks\n- what happens if someone changes it\n- invariants, units, or ranges the type does not carry\n\n**Cut** — the code already says it:\n- restating the signature in prose\n- narrating the steps the body performs\n- paraphrasing the function name\n- history: what it used to do, when it was added\n- a block comment on a three-line private helper\n\n## Reading the ratio\n\nTriage only. Never a target, and never something to optimise toward.\n\n| ratio | usual meaning |\n|---|---|\n| under 5% with new public API | rule 4 is being skipped |\n| 10–25% | unremarkable |\n| over 35% | read every run; usually rule 1 and 2 |\n\nRule 4 work does not move the ratio at all: a one-line doc on a public item is\nnot a run, so `doc` stays flat while `code` grows. That is deliberate. Measure\nrule 4 with the detector in `references\u002Fpublic-surface.md`, never with the\nnumber.\n\nTests skew high and that is often fine — a header explaining what a fixture\nproves is non-obvious behaviour. Judge test files separately from source.\n\n## Output\n\n```\ndoc review · \u003Csource> · \u003Cratio>% documentation\n\ncut      src\u002Fstore.ts:41   (6 lines)  restates the reducer below\nshorten  src\u002Fapi.ts:12     (5 → 1)    one line covers it\nadd      src\u002Fmodels.ts:88             exported const, no doc line\n\nverdict: \u003Cone sentence — what to do before this ships>\n```\n\nOrder findings by how much they cost a reader: bloat in a public doc first,\nprivate-helper noise last. Cite `file:line` for every one, so the fix is one\njump away. If a change is clean, say so in one line and stop — a doc review\nthat invents findings to look thorough is itself the failure mode.\n","# Doc review\n\n## The rules\n\n1. **Brief and easy to follow.**\n2. **Only non-obvious behaviour.** If the code says it, leave it out.\n3. **Clear private helpers need no comment at all.**\n4. **Every public function, type and exported const gets at least a brief line**,\n   so it is described wherever the docs are read.\n\nRules 1–3 delete. Rule 4 adds. Most changes need both directions at once —\na change with too much prose in the internals and none on its public surface\nis the normal case, not the exception.\n\n## Procedure\n\n**1. Measure.**\n\n```bash\ngk doc --base main --json     # what this branch added\ngk doc --json                 # uncommitted, including new files\ngk doc --range A..B --json\n```\n\nRead `totals.ratio`, `files[]`, and `runs[]` (comment blocks ≥2 lines, longest\nfirst). One-line asides are excluded by default — that is the point.\nIf the tool or repository is unavailable, identify the missing measurement.\nContinue from a supplied diff when sufficient; never invent a ratio or install\ntools as a side effect of review. When `gk` is missing, give the user its\ninstall command:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf \\\n  https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Freleases\u002Flatest\u002Fdownload\u002Fgist-cli-installer.sh | sh\n```\n\n**2. Triage with the runs, not the ratio.**\n\nRead every run of 4+ lines. Spot-check two or three shorter ones. The runs list\nis sorted longest-first because length is the cheapest signal of a rule 1 or\nrule 2 violation.\n\n**3. Judge each comment, in this order.**\n\n| Ask | If yes |\n|---|---|\n| Does the code below already say this? | **cut** |\n| Is it a private helper with a clear name and signature? | **cut** |\n| Is it three sentences where one would do? | **shorten** |\n| Does it explain *why*, a constraint, or a consequence? | **keep** |\n\n**4. Check the other direction.**\n\nFind public items in the change with no doc line at all. Per-language patterns:\n[references\u002Fpublic-surface.md](references\u002Fpublic-surface.md). Every one of them is a rule 4 finding.\n\n**5. Report.** Do not edit yet. Findings first, fixes when asked.\n\n## Keep vs cut\n\n**Keep** — the reader cannot get this from the code:\n- why this approach and not the obvious one\n- a constraint imposed from somewhere else: a wire format, an ordering another\n  file asserts, a caller that breaks\n- what happens if someone changes it\n- invariants, units, or ranges the type does not carry\n\n**Cut** — the code already says it:\n- restating the signature in prose\n- narrating the steps the body performs\n- paraphrasing the function name\n- history: what it used to do, when it was added\n- a block comment on a three-line private helper\n\n## Reading the ratio\n\nTriage only. Never a target, and never something to optimise toward.\n\n| ratio | usual meaning |\n|---|---|\n| under 5% with new public API | rule 4 is being skipped |\n| 10–25% | unremarkable |\n| over 35% | read every run; usually rule 1 and 2 |\n\nRule 4 work does not move the ratio at all: a one-line doc on a public item is\nnot a run, so `doc` stays flat while `code` grows. That is deliberate. Measure\nrule 4 with the detector in `references\u002Fpublic-surface.md`, never with the\nnumber.\n\nTests skew high and that is often fine — a header explaining what a fixture\nproves is non-obvious behaviour. Judge test files separately from source.\n\n## Output\n\n```\ndoc review · \u003Csource> · \u003Cratio>% documentation\n\ncut      src\u002Fstore.ts:41   (6 lines)  restates the reducer below\nshorten  src\u002Fapi.ts:12     (5 → 1)    one line covers it\nadd      src\u002Fmodels.ts:88             exported const, no doc line\n\nverdict: \u003Cone sentence — what to do before this ships>\n```\n\nOrder findings by how much they cost a reader: bloat in a public doc first,\nprivate-helper noise last. Cite `file:line` for every one, so the fix is one\njump away. If a change is clean, say so in one line and stop — a doc review\nthat invents findings to look thorough is itself the failure mode.\n",{"name":5,"description":7},"main","e3e4cfd3ffe30ed9a8ef3479e758aacac9c4636d","skills\u002Fgist-doc-review","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist","https:\u002F\u002Fgithub.com\u002Fmsurkovsky","https:\u002F\u002Fsurkovsky.cz\u002F","2026-10-06 04:56:29",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add msurkovsky\u002Fgist --skill gist-doc-review",{"tool":37,"command":38},"bunx","bunx skills add msurkovsky\u002Fgist --skill gist-doc-review",{"tool":40,"command":41},"pnpm","pnpm dlx skills add msurkovsky\u002Fgist --skill gist-doc-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fskills\u002Fgist-doc-review\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fpublic-surface.md","REFERENCE","参考文档",2372,"https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fskills\u002Fgist-doc-review\u002Freferences\u002Fpublic-surface.md",[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M7DBM4VPVT6W1GYRBEJ00KMX","gist-outline","Summarize a codebase's file counts, dominant languages, and size when asked for an overview or when unfamiliar-tree orientation helps the requested work.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fskills\u002Fgist-outline\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M7DBKZCSV1QAQDG6VWF2A2M3","gist-md-review","Let the user review a markdown file in a browser page, commenting on selected text, while you revise it round by round until they approve. Use when the user wants to read and comment on a document themselves, as in \"review docs\u002Fplan.md with me\", \"let me review this doc\", \"I want to comment on the design\", or \"continue the review of docs\u002Fplan.md\". Not for reviewing code, and not when the user asks you to review a document yourself.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fskills\u002Fgist-md-review\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7DBKNKB340B59SNBZKXPAEF","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fexperimental\u002Fmattpocock\u002Fskills\u002Fproductivity\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7DBKM0QBGKNFN3V7SGAQ9YA","wait-what","Stop. That last message did not land: re-pitch it.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fexperimental\u002Fmattpocock\u002Fskills\u002Fproductivity\u002Fwait-what\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7DBKHXYJV0Y3MJ7F1SJ098P","to-questionnaire","Turn a decision you can't fully answer into a questionnaire for someone else to fill in.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fexperimental\u002Fmattpocock\u002Fskills\u002Fproductivity\u002Fto-questionnaire\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M7DBKEN3HAR1DYSV5NNSX1T5","teach","Teach the user a new skill or concept, within this workspace.","https:\u002F\u002Fgithub.com\u002Fmsurkovsky\u002Fgist\u002Fblob\u002Fmain\u002Fexperimental\u002Fmattpocock\u002Fskills\u002Fproductivity\u002Fteach\u002FSKILL.md",[],[]]