[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75JQ90NVYAMJRYTF4SC2E1M":3,"skill-same:01M75JQ90NVYAMJRYTF4SC2E1M":46},{"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":25,"commitSha":26,"skillDirectory":27,"forksCount":14,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M75JQ90NVYAMJRYTF4SC2E1M","code-comments",null,"How to comment source in The Warden's Oak — when a comment is warranted, the 1-2 line budget, and the banned kinds (issue refs, decision narration, cross-layer duplication, echo comments). Use when writing or reviewing any comment or JSDoc block in src\u002F or tests\u002F.","WernerVdM97\u002Fdaily-pixel","WernerVdM97","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F51920192?v=4","01M75JPTS7EV5F4QH79JWF8YCE","Werner V\u002Fd Merwe","01M75JPTTSMZ29EMDP2KRMHVHC",0,"MIT","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002F.pi\u002Fskills\u002Fcode-comments\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: code-comments\ndescription: How to comment source in The Warden's Oak — when a comment is warranted, the 1-2 line budget, and the banned kinds (issue refs, decision narration, cross-layer duplication, echo comments). Use when writing or reviewing any comment or JSDoc block in src\u002F or tests\u002F.\nallowed-tools: Read, Edit, Grep, Glob\n---\n\n# Code Comments\n\nThe rule is in `AGENTS.md`: **code is the source of truth for what it does, and a comment earns its place only by saying what the code cannot, in 1 or 2 lines.** This skill is the worked-example half of it.\n\nUnnarrated source is a project goal, not a preference. Every extra line of prose is a line a reviewer has to read, hold and then check against the code, and a line that drifts the moment the code moves.\n\n## The test to apply\n\nAsk: *could a competent reader get this from the code itself, from `git blame`, or from the PR?* If yes, delete it. If no, keep it and keep it to the point.\n\n## Banned\n\n### 1. Issue and board references\n\n```ts\n\u002F\u002F BAD\n\u002F\u002F #97: the opening round authors the fight's `baseDc`, and the edge pins it from here on.\nbaseDc: state.lastDecideResult.baseDc,\n```\n\n`#97` means nothing to a reader in the file, and the card it points at will be closed and forgotten while the line stays. The commit subject (`fix(#97): …`) and the PR body carry that link; they are one `git log` away and they travel with the change.\n\n### 2. Decision narration\n\n```ts\n\u002F\u002F BAD — eight lines explaining a board card's reasoning\n\u002F\u002F The fight's OWN dc (#97): authored by the opening round's decide beat and pinned on the\n\u002F\u002F `in_combat` edge from then on, so `enemyBonus`, the combat card's `dangerTier` and the\n\u002F\u002F `foeDanger` RESOLVE is handed all describe the same foe in every round of one fight. The\n\u002F\u002F decide model is free to re-author `baseDc` on a CONTINUE round (nothing clamps it), and\n\u002F\u002F reading it here lets the foe's to-hit bonus and its displayed tier drift mid-fight for no\n\u002F\u002F in-world reason. ...\nconst fightDc = cs.baseDc ?? state.lastDecideResult.baseDc;\n\n\u002F\u002F GOOD — the one genuinely non-obvious consequence, two lines\n\u002F\u002F The fallback covers an edge written before the prop existed; folding it back into `cs` is\n\u002F\u002F what bounds it to a single round.\nconst fightDc = cs.baseDc ?? state.lastDecideResult.baseDc;\nif (cs.baseDc === undefined) cs = { ...cs, baseDc: fightDc };\n```\n\nThe commit body is where the *why we changed it* lives, in as much depth as it needs. The code only needs the *why it looks like this*.\n\n### 3. The same rationale at several layers\n\nThis is the single most common failure, and the most expensive to review: one decision restated in the type doc, the producer, the reader, the validator, the prompt builder and the test. It reads as six independent justifications for six unrelated lines, so each has to be checked against the code separately even though it is one fact stated six times.\n\nState it **once**, at the layer a reader debugging that behaviour would actually open. Everywhere else, the name should carry it: `baseDc` on the edge, `dc` on the round summary.\n\n### 4. Echo comments\n\n```ts\n\u002F\u002F BAD — restates the next line\n\u002F\u002F Push the fight DC onto the round summary.\nout.push(`- Fight DC: ${dc} (fixed when the fight opened; any baseDc you author is ignored)`);\n\n\u002F\u002F GOOD — no comment at all; the emitted string says exactly what it means, to the model\nout.push(`- Fight DC: ${dc} (the fight's own DC, fixed when it opened; any baseDc you author is ignored)`);\n```\n\n### 5. Line-number citations into other files\n\n`\u002F\u002F see combat-state.ts:118` is correct until the next edit above line 118, and nothing fails when it goes wrong. Cite the symbol instead, or nothing.\n\n## Carve-outs\n\nWarranted, and still kept brief:\n\n- **Exported helper usage doc.** What the helper is for and how to call it, when the signature alone does not say (units, ordering expectations, which of two similar helpers to reach for).\n- **Test and fixture notes.** The scenario a fixture builds: the dice it feeds, the HP it starts from, what authors what, and why it is shaped that way. Setup is not self-evident from the assertions, and a test whose setup is unexplained is a test nobody dares change. Keep it to the fixture it describes.\n- **A non-obvious constant or threshold**, with where the number came from.\n- **An ordering, idempotency or persistence caveat** that bites if missed.\n- **A broken convention**, or a deliberate exception to a pattern.\n\n## Reviewing a diff for this\n\nRaise as a *style* finding, never a blocking one: `#NNN` references, decision narration, a rationale repeated at more than one layer, echo comments, any comment block over two lines, and cross-file line-number citations.\n\nDo not raise the carve-outs: a helper's usage doc, or a test fixture documenting its own setup. Documenting a test's scenario is not slop; it is the thing that makes the test maintainable.\n","# Code Comments\n\nThe rule is in `AGENTS.md`: **code is the source of truth for what it does, and a comment earns its place only by saying what the code cannot, in 1 or 2 lines.** This skill is the worked-example half of it.\n\nUnnarrated source is a project goal, not a preference. Every extra line of prose is a line a reviewer has to read, hold and then check against the code, and a line that drifts the moment the code moves.\n\n## The test to apply\n\nAsk: *could a competent reader get this from the code itself, from `git blame`, or from the PR?* If yes, delete it. If no, keep it and keep it to the point.\n\n## Banned\n\n### 1. Issue and board references\n\n```ts\n\u002F\u002F BAD\n\u002F\u002F #97: the opening round authors the fight's `baseDc`, and the edge pins it from here on.\nbaseDc: state.lastDecideResult.baseDc,\n```\n\n`#97` means nothing to a reader in the file, and the card it points at will be closed and forgotten while the line stays. The commit subject (`fix(#97): …`) and the PR body carry that link; they are one `git log` away and they travel with the change.\n\n### 2. Decision narration\n\n```ts\n\u002F\u002F BAD — eight lines explaining a board card's reasoning\n\u002F\u002F The fight's OWN dc (#97): authored by the opening round's decide beat and pinned on the\n\u002F\u002F `in_combat` edge from then on, so `enemyBonus`, the combat card's `dangerTier` and the\n\u002F\u002F `foeDanger` RESOLVE is handed all describe the same foe in every round of one fight. The\n\u002F\u002F decide model is free to re-author `baseDc` on a CONTINUE round (nothing clamps it), and\n\u002F\u002F reading it here lets the foe's to-hit bonus and its displayed tier drift mid-fight for no\n\u002F\u002F in-world reason. ...\nconst fightDc = cs.baseDc ?? state.lastDecideResult.baseDc;\n\n\u002F\u002F GOOD — the one genuinely non-obvious consequence, two lines\n\u002F\u002F The fallback covers an edge written before the prop existed; folding it back into `cs` is\n\u002F\u002F what bounds it to a single round.\nconst fightDc = cs.baseDc ?? state.lastDecideResult.baseDc;\nif (cs.baseDc === undefined) cs = { ...cs, baseDc: fightDc };\n```\n\nThe commit body is where the *why we changed it* lives, in as much depth as it needs. The code only needs the *why it looks like this*.\n\n### 3. The same rationale at several layers\n\nThis is the single most common failure, and the most expensive to review: one decision restated in the type doc, the producer, the reader, the validator, the prompt builder and the test. It reads as six independent justifications for six unrelated lines, so each has to be checked against the code separately even though it is one fact stated six times.\n\nState it **once**, at the layer a reader debugging that behaviour would actually open. Everywhere else, the name should carry it: `baseDc` on the edge, `dc` on the round summary.\n\n### 4. Echo comments\n\n```ts\n\u002F\u002F BAD — restates the next line\n\u002F\u002F Push the fight DC onto the round summary.\nout.push(`- Fight DC: ${dc} (fixed when the fight opened; any baseDc you author is ignored)`);\n\n\u002F\u002F GOOD — no comment at all; the emitted string says exactly what it means, to the model\nout.push(`- Fight DC: ${dc} (the fight's own DC, fixed when it opened; any baseDc you author is ignored)`);\n```\n\n### 5. Line-number citations into other files\n\n`\u002F\u002F see combat-state.ts:118` is correct until the next edit above line 118, and nothing fails when it goes wrong. Cite the symbol instead, or nothing.\n\n## Carve-outs\n\nWarranted, and still kept brief:\n\n- **Exported helper usage doc.** What the helper is for and how to call it, when the signature alone does not say (units, ordering expectations, which of two similar helpers to reach for).\n- **Test and fixture notes.** The scenario a fixture builds: the dice it feeds, the HP it starts from, what authors what, and why it is shaped that way. Setup is not self-evident from the assertions, and a test whose setup is unexplained is a test nobody dares change. Keep it to the fixture it describes.\n- **A non-obvious constant or threshold**, with where the number came from.\n- **An ordering, idempotency or persistence caveat** that bites if missed.\n- **A broken convention**, or a deliberate exception to a pattern.\n\n## Reviewing a diff for this\n\nRaise as a *style* finding, never a blocking one: `#NNN` references, decision narration, a rationale repeated at more than one layer, echo comments, any comment block over two lines, and cross-file line-number citations.\n\nDo not raise the carve-outs: a helper's usage doc, or a test fixture documenting its own setup. Documenting a test's scenario is not slop; it is the thing that makes the test maintainable.\n",{"name":5,"description":7,"allowed-tools":24},"Read, Edit, Grep, Glob","dev","96f5ffb582420679625efdf337d44e9ddfcd7c97",".pi\u002Fskills\u002Fcode-comments","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel","https:\u002F\u002Fgithub.com\u002FWernerVdM97","informationalism enthusiast","2026-11-14 17:25:05",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add WernerVdM97\u002Fdaily-pixel --skill code-comments",{"tool":38,"command":39},"bunx","bunx skills add WernerVdM97\u002Fdaily-pixel --skill code-comments",{"tool":41,"command":42},"pnpm","pnpm dlx skills add WernerVdM97\u002Fdaily-pixel --skill code-comments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002F.pi\u002Fskills\u002Fcode-comments\u002FSKILL.md",true,[],[47,53,58,63,68,73],{"skillNo":48,"name":49,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M75JS5K1AHJ25E4XCKRGG38P","decide","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002Fassets\u002Fprompts\u002Fdecision-prompts\u002Fv14\u002Fdecide\u002Fskill.md",[],[],{"skillNo":54,"name":49,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M75JS47KQ0Y0J7GKJGP05CJW","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002Fassets\u002Fprompts\u002Fdecision-prompts\u002Fv13\u002Fdecide\u002Fskill.md",[],[],{"skillNo":59,"name":49,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M75JS2SGKV3FX5F2GY769FY0","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002Fassets\u002Fprompts\u002Fdecision-prompts\u002Fv12\u002Fdecide\u002Fskill.md",[],[],{"skillNo":64,"name":49,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M75JS08B4RD30N35BYPP2BF8","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002Fassets\u002Fprompts\u002Fdecision-prompts\u002Fcurrent_source\u002Fdecide\u002Fskill.md",[],[],{"skillNo":69,"name":49,"nameZh":6,"description":6,"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},"01M75JRYYS3CASN8Q84SZEKCHE","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002Fassets\u002Fprompts\u002Fdecision-prompts\u002F__test-partial__\u002Fdecide\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},"01M75JRW7DRDGXRK7CDQ9HKP3D","releasing","Branch model, POC-beta versioning, and the full cut-a-release procedure for The Warden's Oak. Use when committing\u002Fbranching, merging dev→main, bumping VERSION, writing release notes, or tagging a release.","https:\u002F\u002Fgithub.com\u002FWernerVdM97\u002Fdaily-pixel\u002Fblob\u002Fdev\u002F.pi\u002Fskills\u002Freleasing\u002FSKILL.md",[],[]]