Update to pstack

{
  "description": "Explain how a codebase, subsystem, feature, API, or technical artifact works by inspecting the available source. Use for 'how does X work', code walkthroughs, runtime flows, architecture questions, ownership questions, and 'where should this live'.",
  "included_files": [],
  "name": "how",
  "skill_md_contents": "---\nname: how\ndescription: \"Explain how a codebase, subsystem, feature, API, or technical artifact works by inspecting the available source. Use for 'how does X work', code walkthroughs, runtime flows, architecture questions, ownership questions, and 'where should this live'.\"\n---\n\n# How\n\nExplain how the target actually works.\n\nBuild a useful mental model from the source. Do not produce an annotated file listing, guess from filenames, or describe how this kind of system usually works.\n\nUse this skill for questions like:\n\n- \"How does this work?\"\n- \"Walk me through this feature.\"\n- \"What happens when this request comes in?\"\n- \"How is this subsystem structured?\"\n- \"Where does this logic belong?\"\n- \"Which component owns this?\"\n- \"Is this the right layer?\"\n- \"What is wrong with this architecture?\"\n\n## Get the source first\n\nUse the best source available in the conversation.\n\nPrefer:\n\n1. Connected GitHub repositories, PRs, issues, diffs, and files.\n2. Files the user attached.\n3. Other connected sources with relevant implementation or technical documentation.\n4. Public source when the target is public.\n\nIf the user names a repository, PR, issue, file, class, function, or subsystem that you can access, inspect it before answering.\n\nIf the conversation already contains enough source, use it.\n\nDo not ask the user to paste information you can already access.\n\nIf you cannot access the source needed to answer, say what is missing. Do not fill gaps with guesses.\n\n## Decide what you are explaining\n\nPin down the target before exploring.\n\nIt may be:\n\n- one function or class\n- a request path\n- a UI flow\n- an event flow\n- a service\n- a feature spread across several modules\n- a persistence model\n- an integration\n- a package or module boundary\n- ownership of a domain concept\n\nIf the question is slightly ambiguous, use the most likely interpretation from the conversation and proceed. State the interpretation only when it matters.\n\n## Start where the behavior starts\n\nFind the real entry point.\n\nCommon entry points include:\n\n- an HTTP route\n- a controller\n- a UI event handler\n- a command\n- a message consumer\n- a scheduled job\n- a public service method\n- application startup\n- an external callback\n\nDo not start by collecting every file that mentions the same word.\n\nFind what triggers the behavior, then follow it.\n\n## Trace the flow\n\nFollow the implementation from trigger to result.\n\nWork out:\n\n1. What starts the flow?\n2. What data enters?\n3. Where is it parsed or validated?\n4. Which business rules run?\n5. What state is read?\n6. What state changes?\n7. Which external systems are called?\n8. What response, event, write, or other side effect comes out?\n\nFollow real callers and callees when the source lets you.\n\nFor asynchronous systems, include queues, events, callbacks, retries, and later consumers when they affect the result.\n\nFor UI code, follow the path from the user action through state changes to the rendered result.\n\nFor data-heavy flows, show where the representation changes. For example:\n\n```text\nraw request\n-> transport type\n-> domain type\n-> persistence model\n-> response\n\n```\n\nStop exploring when you can explain the relevant path without skipping a material step.\n\n## Find the concepts that matter\n\nPull out only the concepts needed to understand the flow.\n\nThese may include:\n\n- domain entities\n- state owners\n- services\n- repositories\n- adapters\n- coordinators\n- protocols\n- queues\n- tables\n- configuration\n- important invariants\n\nExplain what each one owns.\n\nDo not turn the answer into a catalogue of classes and files.\n\n## Explain ownership\n\nWhen the question is about placement or architecture, work out:\n\n- who owns the behavior\n- which layer implements it\n- what depends on that layer\n- what that layer depends on\n- where data crosses system boundaries\n- whether framework, transport, persistence, and domain concerns are mixed\n- what callers need to know about the implementation\n\nKeep current state and recommendations separate.\n\nSay:\n\n```text\nToday this lives in X.\n\n```\n\nbefore:\n\n```text\nI would move it to Y because...\n\n```\n\nDo not describe your preferred design as though it already exists.\n\n## Call out the parts people get wrong\n\nInclude non-obvious behavior that would matter to someone changing the code.\n\nExamples:\n\n- state is owned somewhere unexpected\n- a call that looks synchronous continues through an event\n- a value is calculated rather than stored\n- retries can execute the same operation more than once\n- configuration changes the path\n- the same concept has two representations\n- ordering matters\n- a write happens indirectly\n- a path that looks unused is reached dynamically\n- an abstraction requires callers to know its internal rules\n\nOnly include these when the source supports them.\n\n## Explain mode\n\nUse this by default.\n\nStart with a short explanation of what the target is and what job it performs.\n\nThen explain the actual flow in order.\n\nInclude the important concepts as they become relevant rather than dumping definitions up front.\n\nReference concrete files, functions, types, PRs, or other source locations when useful.\n\nFor a larger subsystem, a compact file map can help:\n\n```text\napi/\n  request entry point\n\ndomain/\n  business rules\n\nstorage/\n  persistence\n\nevents/\n  asynchronous follow-up\n\n```\n\nDo not list every related file.\n\nFinish with the few gotchas that matter.\n\nThe structure should fit the question. A small function does not need five sections.\n\n## Critique mode\n\nUse this when the user asks what is wrong, what should change, or where something should live.\n\nUnderstand the current system first. Then critique it.\n\nLook for concrete problems such as:\n\n- unclear ownership\n- dependencies pointing the wrong way\n- the same business rule implemented in several places\n- framework code mixed with business logic\n- database or transport types leaking through domain APIs\n- shared mutable state\n- unnecessary coupling\n- abstractions that expose their internal rules\n- layers that only pass calls through\n- one concept split across unrelated lifecycle modules\n- validation repeated deep inside trusted code\n- data structures that allow impossible states\n\nDo not manufacture problems because the user asked for a critique.\n\nGroup findings only when useful:\n\n- Act on: worth changing.\n- Consider: a real tradeoff, but not an obvious change.\n- Noted: useful context, no change needed.\n- Dismissed: looked suspicious but the source shows it is fine.\n\nFor anything worth changing, say what is wrong, where it happens, why it matters, and the smallest useful correction.\n\n## Evidence\n\nTie factual claims to source you inspected.\n\nCite files, symbols, PRs, issues, or connected-source results when citations are available.\n\nIf something is an inference, say so.\n\nNever claim you read, searched, ran, or verified something you could not access.\n\nCode is good evidence for what the system does. It is weak evidence for why somebody originally designed it that way.\n\nUse the `why` skill for historical rationale when it is available.\n\n## Writing\n\nApply the `unslop` skill to the answer.\n\nUse the same name for the same concept throughout the explanation.\n\nPrefer concrete mechanisms over architecture jargon.\n\nExplain the path a value, request, event, or state change takes.\n\nDo not narrate the investigation unless the user asks.\n\nDo not paste large blocks of source when naming the relevant symbol is enough.\n\nReply with the explanation, not a report about how you produced it."
}