[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CV98WPFSCATXMEVZ3QFYE5":3,"skill-same:01M7CV98WPFSCATXMEVZ3QFYE5":71},{"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":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7CV98WPFSCATXMEVZ3QFYE5","craft-why",null,"Find why code is shaped this way: anchor in git history, fan out one investigator per evidence source, synthesize into confidence tiers. Use for design rationale, tradeoffs, motivating incidents, or where a number came from.","TudeOrangBiasa\u002Fskills-for-agents","TudeOrangBiasa","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F125188681?v=4","01M7CV804RMMCVN5M0D4ZCQ6D8","TudeStillLearning!","01M7CV805CRFTQY48WZ6JK57YK",1,"MIT","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\ndescription: \"Find why code is shaped this way: anchor in git history, fan out one investigator per evidence source, synthesize into confidence tiers. Use for design rationale, tradeoffs, motivating incidents, or where a number came from.\"\nname: craft-why\n---\n# Why\n\nFind what forces shaped a piece of code: the decision, tradeoff, incident, or constraint behind it. Companion to `craft-how` (what it does). Code shows what it does, never why it exists; the why lives in commits, PRs, tickets, docs, and conversations.\n\nInvestigators run in agent mode with tool access (never a read-only harness mode that strips it), but write nothing.\n\n## 1. Understand the target and the question\n\nThe target is usually a chunk of code, a pattern, a feature, or a named design decision; the question is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep. A vague target (\"why do we do it this way?\" with no clear referent) means guessing from conversation context (open files, recent edits, what was just discussed), stating your interpretation briefly, then proceeding; the user redirects if you are off.\n\n## 2. Build the code anchor\n\nSeed context, built inline and passed to every investigator and to the synthesizer: file paths with line ranges, key symbols, the last commits touching the target (`git blame -L \u003Cstart>,\u003Cend> \u003Cfile>`, `git log --follow -p -- \u003Cfile>`, `git log --oneline -20 -- \u003Cfile>`, `git log -1 --format=%B \u003Ccommit>` to extract PR numbers from the `(#1234)` pattern in merge subjects), PR bodies and discussion for substantive commits (`gh pr view \u003Cnumber> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`), and linked ticket IDs.\n\n## 3. Spawn one investigator per available source\n\nDefault to the full parallel investigation: a complete coverage map, not a minimal one. Document the null, do not skip the search.\n\nGit history always runs. Tracker, long-form docs, team chat, observability, error tracking, and analytics run when a tool reaches them; each owns exactly one source, all in one round so they run concurrently. Briefs are self-contained; models follow the repo model map (`craft-why-investigator` role) when one exists. Build each brief from [INVESTIGATOR-BRIEF.md](INVESTIGATOR-BRIEF.md), pasting in the category playbook from [SOURCES.md](SOURCES.md). When a tool could fit more than one category, assign it to its primary evidence and record the ambiguity in the coverage map.\n\nEach category surfaces one shape of why, which also names the gap when it returns empty:\n\n1. **Source control** (git, `gh`, comments, tests). The only guaranteed source. Best at implementation-time rationale captured during review.\n2. **Tracker.** Best at the product or business forcing function; strongest when the why is external to engineering.\n3. **Long-form docs.** Best at design rationale written before it became code.\n4. **Team chat.** Best at deliberation that never reached a doc; especially important when the paper trail is thin.\n5. **Observability.** Best at infrastructure and runtime reality that motivated the code (timeouts, retries, rate limits, circuit breakers).\n6. **Error tracking.** Best at the specific exceptions that motivated defensive or corrective code (catch blocks, null guards, retries).\n7. **Analytics.** Best at product and data reality that shaped the code (flag-gated code, experiments, migrations, where a number came from).\n\nWhen the target looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), add incident-flavored queries inside each investigator's own source (incident or sev tickets, incident channels around the ship dates, \"fix for incident\" style commit messages).\n\nA category is skipped only with an explicit written justification that goes in the final Sources Consulted: no tool reaches it in this environment (flagged as a gap, not a choice), or it is provably irrelevant (a high bar, e.g. error tracking skipped for a build-time script with no runtime path). A trivial target whose PR description already holds the complete answer may be answered inline only after confirming every available search would be redundant; this should be rare.\n\nEach investigator works careful, cautious, and precise: cast a wide net before narrowing, read each item whole (the evidence hides in comments and follow-ups), follow links inside its own source only (cross-source references go under Additional Leads for that source's investigator), quote verbatim with exact location, and record what was searched including empty searches. Gather, do not conclude: mechanics are not motivation, code style is not evidence of intent, contradictions are reported never smoothed over, and no silent substitutions (evidence about feature Y never answers a question about feature X). Never invent; a partial finding stays labeled partial.\n\n## 4. Synthesize with confidence tiers\n\nOne synthesizer (`craft-why-synthesizer` role) merges findings. It reads [EPISTEMICS.md](EPISTEMICS.md) in full first (brief template: [SYNTHESIZER-BRIEF.md](SYNTHESIZER-BRIEF.md)), merges overlapping citations into one authoritative reference, surfaces contradictions side by side instead of picking one, spot-checks uncertain citations against the codebase or tools instead of propagating errors, and never cites code as evidence for its own intent.\n\nEvery claim sits in one tier, and phrasing matches the tier:\n\n- **Direct.** An author wrote the why (PR description, ticket, comment, doc, chat message). Phrased confident, present tense, cited.\n- **Supported.** Indirect evidence converges from several sources, none stating it. Phrased confident but derived, every item cited.\n- **Inferred.** A reasonable reading nothing states explicitly. Hedged with the chain shown (\"given A and B, C seems likely because D\").\n- **Speculative.** A plausible guess other explanations fit equally well. Marked as a guess, kept with competing hypotheses.\n- **Unknown.** Searched and found nothing. A valid outcome: name each source searched and what was asked of it.\n\nDo not retrofit a clean rationale onto messy history, do not confirm a hypothesis the user embedded without independent evidence, and do not turn an absence of evidence into evidence of absence. Confidence words (because, the reason is, fixes, the team decided) need an adjacent citation; hedges (appears to, suggests, plausibly) mark interpretation. Banned: obviously, clearly, of course, dismissive just, \"I think\".\n\nBefore finalizing: every claim in What We Found and What We Can Reasonably Infer has a citation or moves to Inferred or Hypotheses; every contradiction noticed is surfaced; What We Don't Know names specific gaps. If no gaps are mentioned, the search was incomplete.\n\nBeware recency bias: the most recent commit is rarely authoritative; the current shape is often the accretion of many earlier decisions. Trace back.\n\n## 5. Present\n\nPresent the synthesis; light edits for clarity are fine, but do not rewrite the confidence language.\n\n## Output sections\n\nThe Question (one or two sentences), The Code in Question (paths, lines, symbols, two or three lines), What We Found (`[Direct]` and `[Supported]` claims, each quoted or paraphrased and cited), What We Can Reasonably Infer (`[Inferred]` bullets with visible inference chains; skip when nothing), Competing Hypotheses (each with evidence for and evidence against or missing; skip when one answer is clear), What We Don't Know (unanswered questions, empty searches, unavailable sources with why, people who would likely know), Sources Consulted (one line per source, including empty and skipped ones with reasons), Confidence Summary (one or two sentences grading each part of the answer). When the question is a precursor to changing the code, convert the findings into a Preserve \u002F Change \u002F Avoid \u002F Risk constraint set for planning the change.\n","# Why\n\nFind what forces shaped a piece of code: the decision, tradeoff, incident, or constraint behind it. Companion to `craft-how` (what it does). Code shows what it does, never why it exists; the why lives in commits, PRs, tickets, docs, and conversations.\n\nInvestigators run in agent mode with tool access (never a read-only harness mode that strips it), but write nothing.\n\n## 1. Understand the target and the question\n\nThe target is usually a chunk of code, a pattern, a feature, or a named design decision; the question is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep. A vague target (\"why do we do it this way?\" with no clear referent) means guessing from conversation context (open files, recent edits, what was just discussed), stating your interpretation briefly, then proceeding; the user redirects if you are off.\n\n## 2. Build the code anchor\n\nSeed context, built inline and passed to every investigator and to the synthesizer: file paths with line ranges, key symbols, the last commits touching the target (`git blame -L \u003Cstart>,\u003Cend> \u003Cfile>`, `git log --follow -p -- \u003Cfile>`, `git log --oneline -20 -- \u003Cfile>`, `git log -1 --format=%B \u003Ccommit>` to extract PR numbers from the `(#1234)` pattern in merge subjects), PR bodies and discussion for substantive commits (`gh pr view \u003Cnumber> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`), and linked ticket IDs.\n\n## 3. Spawn one investigator per available source\n\nDefault to the full parallel investigation: a complete coverage map, not a minimal one. Document the null, do not skip the search.\n\nGit history always runs. Tracker, long-form docs, team chat, observability, error tracking, and analytics run when a tool reaches them; each owns exactly one source, all in one round so they run concurrently. Briefs are self-contained; models follow the repo model map (`craft-why-investigator` role) when one exists. Build each brief from [INVESTIGATOR-BRIEF.md](INVESTIGATOR-BRIEF.md), pasting in the category playbook from [SOURCES.md](SOURCES.md). When a tool could fit more than one category, assign it to its primary evidence and record the ambiguity in the coverage map.\n\nEach category surfaces one shape of why, which also names the gap when it returns empty:\n\n1. **Source control** (git, `gh`, comments, tests). The only guaranteed source. Best at implementation-time rationale captured during review.\n2. **Tracker.** Best at the product or business forcing function; strongest when the why is external to engineering.\n3. **Long-form docs.** Best at design rationale written before it became code.\n4. **Team chat.** Best at deliberation that never reached a doc; especially important when the paper trail is thin.\n5. **Observability.** Best at infrastructure and runtime reality that motivated the code (timeouts, retries, rate limits, circuit breakers).\n6. **Error tracking.** Best at the specific exceptions that motivated defensive or corrective code (catch blocks, null guards, retries).\n7. **Analytics.** Best at product and data reality that shaped the code (flag-gated code, experiments, migrations, where a number came from).\n\nWhen the target looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), add incident-flavored queries inside each investigator's own source (incident or sev tickets, incident channels around the ship dates, \"fix for incident\" style commit messages).\n\nA category is skipped only with an explicit written justification that goes in the final Sources Consulted: no tool reaches it in this environment (flagged as a gap, not a choice), or it is provably irrelevant (a high bar, e.g. error tracking skipped for a build-time script with no runtime path). A trivial target whose PR description already holds the complete answer may be answered inline only after confirming every available search would be redundant; this should be rare.\n\nEach investigator works careful, cautious, and precise: cast a wide net before narrowing, read each item whole (the evidence hides in comments and follow-ups), follow links inside its own source only (cross-source references go under Additional Leads for that source's investigator), quote verbatim with exact location, and record what was searched including empty searches. Gather, do not conclude: mechanics are not motivation, code style is not evidence of intent, contradictions are reported never smoothed over, and no silent substitutions (evidence about feature Y never answers a question about feature X). Never invent; a partial finding stays labeled partial.\n\n## 4. Synthesize with confidence tiers\n\nOne synthesizer (`craft-why-synthesizer` role) merges findings. It reads [EPISTEMICS.md](EPISTEMICS.md) in full first (brief template: [SYNTHESIZER-BRIEF.md](SYNTHESIZER-BRIEF.md)), merges overlapping citations into one authoritative reference, surfaces contradictions side by side instead of picking one, spot-checks uncertain citations against the codebase or tools instead of propagating errors, and never cites code as evidence for its own intent.\n\nEvery claim sits in one tier, and phrasing matches the tier:\n\n- **Direct.** An author wrote the why (PR description, ticket, comment, doc, chat message). Phrased confident, present tense, cited.\n- **Supported.** Indirect evidence converges from several sources, none stating it. Phrased confident but derived, every item cited.\n- **Inferred.** A reasonable reading nothing states explicitly. Hedged with the chain shown (\"given A and B, C seems likely because D\").\n- **Speculative.** A plausible guess other explanations fit equally well. Marked as a guess, kept with competing hypotheses.\n- **Unknown.** Searched and found nothing. A valid outcome: name each source searched and what was asked of it.\n\nDo not retrofit a clean rationale onto messy history, do not confirm a hypothesis the user embedded without independent evidence, and do not turn an absence of evidence into evidence of absence. Confidence words (because, the reason is, fixes, the team decided) need an adjacent citation; hedges (appears to, suggests, plausibly) mark interpretation. Banned: obviously, clearly, of course, dismissive just, \"I think\".\n\nBefore finalizing: every claim in What We Found and What We Can Reasonably Infer has a citation or moves to Inferred or Hypotheses; every contradiction noticed is surfaced; What We Don't Know names specific gaps. If no gaps are mentioned, the search was incomplete.\n\nBeware recency bias: the most recent commit is rarely authoritative; the current shape is often the accretion of many earlier decisions. Trace back.\n\n## 5. Present\n\nPresent the synthesis; light edits for clarity are fine, but do not rewrite the confidence language.\n\n## Output sections\n\nThe Question (one or two sentences), The Code in Question (paths, lines, symbols, two or three lines), What We Found (`[Direct]` and `[Supported]` claims, each quoted or paraphrased and cited), What We Can Reasonably Infer (`[Inferred]` bullets with visible inference chains; skip when nothing), Competing Hypotheses (each with evidence for and evidence against or missing; skip when one answer is clear), What We Don't Know (unanswered questions, empty searches, unavailable sources with why, people who would likely know), Sources Consulted (one line per source, including empty and skipped ones with reasons), Confidence Summary (one or two sentences grading each part of the answer). When the question is a precursor to changing the code, convert the findings into a Preserve \u002F Change \u002F Avoid \u002F Risk constraint set for planning the change.\n",{"name":5,"description":7},"main","d26d63fb9a1a8091ba1d908b1b35738b60e8be79","skills\u002Fmodel-invoked\u002Fcraft-why",0,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa","2026-11-05 23:44:38",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add TudeOrangBiasa\u002Fskills-for-agents --skill craft-why",{"tool":37,"command":38},"bunx","bunx skills add TudeOrangBiasa\u002Fskills-for-agents --skill craft-why",{"tool":40,"command":41},"pnpm","pnpm dlx skills add TudeOrangBiasa\u002Fskills-for-agents --skill craft-why","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FSKILL.md",true,[45,51,55,59,63,67],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",87,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002Fagents\u002Fopenai.yaml",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"CREDITS.md",1071,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FCREDITS.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"EPISTEMICS.md",6007,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FEPISTEMICS.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"INVESTIGATOR-BRIEF.md",5200,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FINVESTIGATOR-BRIEF.md",{"path":64,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":65,"sourceHtmlUrl":66},"SOURCES.md",12015,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FSOURCES.md",{"path":68,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":69,"sourceHtmlUrl":70},"SYNTHESIZER-BRIEF.md",6111,"https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fmodel-invoked\u002Fcraft-why\u002FSYNTHESIZER-BRIEF.md",[72,79,86,93,100,107],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7CVDKFYKNEY024TK36QAA2R","whips","Route any non-trivial task through one entry: match a playbook, drive HIT skills plus subagents, open a reviewed ready PR with ship-pr-shaped evidence.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fwhips\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7CVDFG46BBHV71Q5JVZ7XZT","verify-upkeep","Periodic upkeep for a project's verification skill: source wave plus live pass per feature, at most one PR of proven corrections. Use to audit the verify skill.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fverify-upkeep\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M7CVDB20QNGAPR8T5YXDRNT9","verify-statechart","Check a TLA+ model of a system that moves between states, such as a product flow, a protocol, or a service, and draw it as a Mermaid statechart. The report gives the shortest path to each state that breaks a rule. Use to show a bug as a path through states.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fverify-statechart\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M7CVD6Y3W2A12ZDEQBS39QPD","verify-new","Generate a project-local skill that drives the app like a user (launch, doctor, drive, evidence, feature map), proven once. Use when a project has no scripted proof.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fverify-new\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M7CVD2WTQ83ETMQ82GWWZAAV","ship-triage","Move issues and external PRs through a state machine of triage roles, categorise, verify, interview if needed, and write agent-ready briefs.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fship-triage\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":19},"01M7CVCYS0S8S8XW68V819QKZ6","ship-runner","Run ready-for-agent issue queues on any schedule through \u002Fwhips intake, one fresh worktree each, landing per risk tier, with the agent and model you pick at setup.","https:\u002F\u002Fgithub.com\u002FTudeOrangBiasa\u002Fskills-for-agents\u002Fblob\u002Fmain\u002Fskills\u002Fuser-invoked\u002Fship-runner\u002FSKILL.md",[],[]]