{"id":18126,"plugin_id":"plugins_6a85a87df50c8191bd7f010bb7b17794","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:38.185Z","digest":"61f4b4181f75108996ee29536c8c0515953d970cd6d4b6194484b31350727bb5","against":null,"payload":{"description":"Investigate why a codebase, feature, design decision, threshold, workaround, or architectural choice exists by tracing evidence across the sources available to ChatGPT. Use for 'why does X work this way', 'why did we choose Y', design rationale, regressions, postmortems, historical context, and tradeoff questions.","included_files":[],"name":"why","skill_md_contents":"---\nname: why\ndescription: \"Investigate why a codebase, feature, design decision, threshold, workaround, or architectural choice exists by tracing evidence across the sources available to ChatGPT. Use for 'why does X work this way', 'why did we choose Y', design rationale, regressions, postmortems, historical context, and tradeoff questions.\"\n---\n# Why\n\nInvestigate why something exists or works the way it does.\n\nThe goal is to recover the evidence behind a decision, not invent a plausible explanation from the current code.\n\nUse this skill for questions like:\n\n* \"Why was this designed this way?\"\n* \"Why do we use X instead of Y?\"\n* \"Why does this workaround exist?\"\n* \"Why is this limit 500?\"\n* \"What caused this regression?\"\n* \"What led to this architecture?\"\n* \"Was this added for a customer, incident, or technical constraint?\"\n* \"What alternatives did we consider?\"\n\nUse `how` when the question is about what the system does or how it runs. Use `why` when the question is about intent, history, constraints, or tradeoffs.\n\n## Evidence before explanation\n\nDo not infer historical intent from the shape of the current code unless no better evidence exists.\n\nLook for direct evidence first.\n\nUseful sources include:\n\n* Git history\n* commits\n* pull requests\n* review comments\n* GitHub issues\n* Linear or another issue tracker\n* design documents\n* RFCs\n* ADRs\n* project notes\n* team chat\n* incident reports\n* error tracking\n* observability data\n* product analytics\n* code comments and tests when they record a constraint\n\nUse whatever sources ChatGPT can access in the current conversation.\n\nIf the user names a repository, ticket, PR, document, incident, or other source that is accessible, inspect it before answering.\n\nDo not ask the user to paste information that is already available through a connected source.\n\n## Start with the target\n\nPin down what decision you are investigating.\n\nThe target may be:\n\n* a function\n* a class\n* a configuration value\n* a feature\n* an API\n* an architectural pattern\n* a guard or workaround\n* a database field\n* a retry policy\n* a timeout\n* a threshold\n* a deleted or legacy path\n* a change in behavior\n\nFind the concrete code or artifact first when one exists.\n\nRecord the important names that can lead you into the history:\n\n* file paths\n* symbols\n* configuration keys\n* commit hashes\n* PR numbers\n* issue IDs\n* feature names\n* error messages\n* customer or project names already present in the source\n\nThese are search terms, not conclusions.\n\n## Follow the evidence trail\n\nStart with the source closest to the implementation.\n\nFor code, this usually means:\n\n1. Find the relevant file and symbol.\n2. Find commits that changed it.\n3. Find the PRs connected to those commits.\n4. Read the PR description and discussion.\n5. Follow linked issues, tickets, documents, and incidents.\n6. Search other connected sources using the concrete names you found.\n\nA useful clue should lead to the next source.\n\nFor example:\n\n```text\ncode\n-> commit\n-> PR\n-> Linear ticket\n-> design document\n-> incident\n```\n\nDo not search every source using only the broad feature name when a commit, ticket ID, error string, or exact symbol gives you a better query.\n\n## Search the sources that matter\n\nUse available connected sources when they can contain part of the answer.\n\n### Source control\n\nLook for:\n\n* commit messages\n* PR descriptions\n* review comments\n* linked issues\n* reverted changes\n* earlier implementations\n* tests added with the change\n* comments that name a constraint\n\nSource control is often the strongest evidence because it sits close to the change that shipped.\n\n### Issue trackers\n\nLook for:\n\n* the original problem statement\n* acceptance criteria\n* customer requests\n* scope changes\n* parent initiatives\n* bug reports\n* linked incidents\n* implementation discussion\n\nTickets often explain the product or business reason better than the code does.\n\n### Long-form documents\n\nLook for:\n\n* RFCs\n* ADRs\n* design docs\n* PRDs\n* postmortems\n* meeting notes\n* architecture documents\n\nThese are especially useful for alternatives considered and rejected.\n\n### Team chat\n\nWhen available, look for:\n\n* the feature name\n* PR links\n* ticket IDs\n* error messages\n* discussion near the date of the change\n* incident channels\n* conversations involving the authors or reviewers\n\nChat often contains decisions that never made it into the formal record.\n\n### Error and observability data\n\nUse these when the target looks like a response to runtime behavior.\n\nExamples include:\n\n* retries\n* timeouts\n* circuit breakers\n* null guards\n* rate limits\n* memory limits\n* backoff\n* defensive checks\n* feature flags\n\nLook for errors, incidents, metric changes, or release correlations that line up with the code change.\n\n### Product data\n\nUse product analytics when a threshold, rollout, experiment, or user behavior may have shaped the decision.\n\nLook for evidence such as:\n\n* usage distributions\n* experiment results\n* feature adoption\n* traffic levels\n* data volumes\n* rollout dates\n\nDo not invent a data-driven rationale just because a number looks deliberate.\n\n## Treat missing evidence as missing evidence\n\nA search that finds nothing is useful.\n\nSay which source you checked and that it did not contain evidence for the decision.\n\nDo not turn an empty search into:\n\n\"therefore the decision was probably made informally.\"\n\nThat is still an inference.\n\nThe correct answer may be:\n\n\"We can see when this changed and what it does, but I could not find a recorded reason for choosing this design.\"\n\nThat is better than a convincing story with no source behind it.\n\n## Separate fact from inference\n\nKeep three levels clear.\n\n### Direct evidence\n\nThe source explicitly states the reason.\n\nExamples:\n\n* a PR says the old implementation caused duplicate charges\n* a ticket says a customer requires a 15 minute grace period\n* a postmortem says retries caused duplicate writes\n\nState these confidently and cite the source.\n\n### Strong inference\n\nSeveral pieces of evidence point to the same conclusion, but nobody states it directly.\n\nSay:\n\n* \"This appears to have been...\"\n* \"The evidence suggests...\"\n* \"The most likely reason is...\"\n\nThen explain the evidence.\n\n### Unknown\n\nThe record does not support an answer.\n\nSay so.\n\nDo not promote an inference to fact because it sounds sensible.\n\n## Check chronology\n\nDates matter.\n\nBuild the smallest useful timeline when several sources are involved.\n\nFor example:\n\n```text\n12 May\nproduction errors increase\n\n14 May\nticket created\n\n16 May\nPR opened\n\n18 May\nfix merged\n\n19 May\nerrors stop\n```\n\nChronology can support a conclusion, but correlation alone does not prove intent.\n\nA change merging after an incident does not automatically mean the incident caused it.\n\nLook for the link in a PR, ticket, comment, or document.\n\n## Look for alternatives\n\nWhen the question asks why X instead of Y, find evidence that Y was actually considered.\n\nDo not manufacture rejected alternatives from your own architecture knowledge.\n\nDistinguish:\n\n* an alternative the team explicitly considered\n* an alternative that existed in an earlier implementation\n* an alternative you think would have been possible\n\nOnly the first two are historical evidence.\n\nYou may discuss the third as your own analysis, but label it separately.\n\n## Surface contradictions\n\nHistory is messy.\n\nA ticket may say one thing while the merged PR does another.\n\nA design document may describe an approach that was abandoned during implementation.\n\nA comment may claim a workaround is temporary even though it became permanent.\n\nWhen sources disagree, show the disagreement.\n\nDo not silently choose the cleaner story.\n\nPrefer the source closest to the final decision when judging what actually shipped, but preserve earlier sources when they explain how the decision changed.\n\n## Handle current code carefully\n\nThe current implementation can tell you:\n\n* what exists now\n* what behavior survived\n* what assumptions are encoded\n* what constraints tests enforce\n\nIt cannot reliably tell you why those choices were originally made.\n\nDo not write:\n\n\"The code uses a queue because the team wanted loose coupling.\"\n\nunless a source says that.\n\nThe safe version is:\n\n\"The current design uses a queue between X and Y. I found no source that records why that choice was made.\"\n\n## For regressions and incidents\n\nWhen investigating a regression, answer a slightly different question.\n\nFind:\n\n* the last known good behavior\n* the change that altered it\n* what that change was trying to achieve\n* the failure it introduced\n* when the failure became visible\n* whether earlier fixes were attempted\n* whether any fix was reverted\n* what remains unresolved\n\nKeep cause and motivation separate.\n\nA PR may have had a valid goal and still introduced the regression.\n\n## For thresholds and constants\n\nWhen investigating a number such as a timeout, limit, grace period, or batch size, search for the number itself as well as the symbol that contains it.\n\nLook in:\n\n* git history\n* PR discussion\n* tickets\n* documents\n* incidents\n* dashboards\n* analytics\n\nIf you cannot find where the number came from, say that the value is unexplained.\n\nDo not reverse-engineer a neat justification from the number.\n\n## Answer structure\n\nLead with the best-supported answer.\n\nFor a small question, a few paragraphs may be enough.\n\nFor a larger investigation, use this shape when it helps.\n\n### What we know\n\nState the reason supported by direct evidence.\n\n### Evidence\n\nWalk through the important sources in chronological or causal order.\n\nDo not dump every search result.\n\n### What changed\n\nExplain how the decision evolved when the record shows more than one design.\n\n### Confidence\n\nSay whether the conclusion is:\n\n* directly documented\n* strongly supported\n* plausible but unproven\n* unknown\n\nExplain the gap when confidence is limited.\n\n### Open questions\n\nInclude only unresolved questions that materially affect the conclusion.\n\n## Citations\n\nCite the source behind claims about intent.\n\nPrefer specific references such as:\n\n* PR number\n* issue or ticket ID\n* commit\n* document\n* chat thread\n* incident\n* error-tracker issue\n\nWhen ChatGPT can provide a native citation, use it.\n\nA reader should be able to trace the important claims back to evidence.\n\n## Writing\n\nApply the `unslop` skill to the final answer.\n\nUse plain language.\n\nDo not turn the investigation into detective-roleplay.\n\nDo not pad weak evidence with confident prose.\n\nDo not narrate every search you performed.\n\nGive the user the reason, the evidence, the uncertainty, and any contradiction that matters.\n\nReply with the investigation itself, not a report about the workflow.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}