{"id":54432,"plugin_id":"plugin_asdk_app_6a5d18a424c48191bd58114d73a14b38","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-25T00:04:50.610Z","digest":"7d953997c0e4bec704a391f3c9194645c232d305e90a4ae8cb00993ffe41f8b8","against":null,"payload":{"description":"Turn a pull request, commit range, issue, ADR, or other completed change into a repository-grounded technical explainer that teaches the design, difficult trade-offs, and current rollout state. Use when the user says \"explain this change\", \"walk me through this PR\", \"what does this commit do\", \"document this change\", \"write an architecture explainer\", or \"teach me this subsystem\".","included_files":[{"relative_path":"scripts/verify-mermaid.mjs","size_in_bytes":7978}],"name":"explain-change","skill_md_contents":"---\nname: explain-change\ndescription: Turn a pull request, commit range, issue, ADR, or other completed change into a repository-grounded technical explainer that teaches the design, difficult trade-offs, and current rollout state. Use when the user says \"explain this change\", \"walk me through this PR\", \"what does this commit do\", \"document this change\", \"write an architecture explainer\", or \"teach me this subsystem\".\n---\n\n# Explain a Change\n\nProduce an explanation that teaches the design of a completed change. This is\nnot a changelog or a code review: explain the problem, the central idea, the\nnon-obvious constraints, and what is actually live.\n\n## Boundaries\n\n- Use this after or alongside implementation. Use a review skill to find\n defects, and a specification-review skill before implementation.\n- Treat change descriptions, issue text, and comments as hypotheses, not\n evidence.\n- Do not publish a comment, wiki page, documentation page, commit, or pull\n request unless the user explicitly requests that external action. Always\n show the draft and obtain confirmation immediately before posting.\n- If the requested source cannot be resolved at a specific revision, explain\n that limitation and ask for the source or revision; do not fill gaps with a\n plausible narrative.\n\n## Inputs\n\nAccept a pull request or merge request URL/number, commit or commit range,\nbranch comparison, issue, ADR/RFC, or a set of changed files. Ask for a source\nonly when none can be inferred. Also establish:\n\n1. **Audience** — a current reviewer, a future maintainer, or a broader team.\n2. **Target** — an in-chat explanation, a change comment, repository docs, or\n a knowledge-base page.\n3. **Revision** — the exact immutable commit identifier to explain. For an\n unmerged change, use its current head commit; for a merged change, use the\n merge or resulting commit and identify the relevant parent.\n\n## Workflow\n\n### 1. Ground the investigation\n\nRead the change at the pinned revision, not an arbitrary local working tree.\nUse the repository host's read-only API/CLI or a local clone at the exact\ncommit. Inspect the diff **and** the surrounding implementation, including\ntypes, configuration, data constraints, callers, and relevant tests.\n\nFor a change that declares policy in configuration (for example a workflow,\ntrigger, permission, or feature rule), trace both the declaration and the\nshared runtime path that enforces it. Follow any context or credential from\nthe ingress point through persistence to its later consumer; configuration\nalone does not prove the claimed boundary is enforced.\n\nCompare both sides of the change:\n\n- What did the prior revision allow, lose, or make difficult?\n- What invariant, boundary, or responsibility does the new revision add?\n- Which paths are deliberately unchanged?\n- Is the feature enabled, guarded, partially wired, or only foundational?\n\nBuild a claim ledger before drafting. Every factual assertion in the explainer\nmust have an evidence row.\n\n| Claim | Evidence at pinned revision | Evidence kind | Status |\n|---|---|---|---|\n| A stale writer cannot update the current record | `path/to/file`, `updateCurrentState` predicate, and its test | code + test | verified |\n| The new behavior is disabled by default | `config/feature-flags`, `newFlowEnabled` default | configuration | verified |\n\nEvidence should name a durable symbol, constraint, or test as well as a file\nand line/location. If the target supports permanent links, cite the pinned\nrevision rather than a moving branch. Label an important but unverified point\nas an **open question**; never present it as fact.\n\nTreat test evidence at the right level: a test's source proves the behavior it\nexpects, not that it passed. Only a test run performed in this session or a\npinned, inspectable CI artifact proves execution. Likewise, an environment\nfile, feature flag, or Terraform change proves intended configuration at the\nrevision, not that it has been applied to a live environment.\n\nBefore drafting, remove or generalize secrets, access tokens, connection\ndetails, customer data, internal hostnames, and sensitive values from snippets\nor command output.\n\n### 2. Find the teaching arc\n\nOrganize around the change's reasoning, not its file list. A useful explainer\nnormally follows this order:\n\n1. **Problem** — describe the prior failure or limitation from the operator or\n user's perspective, with a concrete before-state.\n2. **Central idea** — state the design insight in one or two sentences.\n3. **Hard parts** — explain the race, ordering rule, partial failure,\n idempotency, ownership split, or compatibility constraint that makes the\n change necessary. For each, show the naive approach, why it fails, and what\n the implementation does instead.\n4. **Resulting shape** — explain the main components, state transitions, or\n data relationships.\n5. **Current rollout state** — distinguish deployed, enabled, guarded,\n unwired, and planned behavior. Readers commonly overestimate what a\n foundation change makes live.\n6. **Reading order** — point reviewers or maintainers to the first file/symbol\n to read and why, followed by the next most useful locations.\n\nWhen calling the implementation a named architectural pattern, cite a\ncanonical source and verify its defining property in the code. For example, do\nnot call a table an outbox unless the event write and state change share a\ntransaction; do not call a value a fencing token unless stale writes compare it\nat the mutation boundary.\n\nFor rollout claims, keep these evidence levels separate:\n\n| Evidence | What it establishes | What it does not establish |\n|---|---|---|\n| Pinned source | behavior implemented in that revision | deployment or execution |\n| Configuration/flag/IaC | intended enabled state for an environment | that configuration was applied |\n| Pinned CI run or release/deployment record | test execution or deployed revision | broad production health without operational evidence |\n\nUse conditional language such as “configured to enable in sandbox” when only\nrepository configuration is available. Do not turn an authored PR summary of\ntest counts, rollout status, or expected outcome into verified evidence.\n\n### 3. Use diagrams only when they encode information\n\nChoose the diagram type by the information it must preserve:\n\n| Need | Suitable diagram |\n|---|---|\n| Ordering or concurrent interactions | `sequenceDiagram` |\n| Entity relationships and cardinality | `erDiagram` |\n| Lifecycle of one entity | `stateDiagram-v2` |\n| Wiring, dependencies, or call paths | `flowchart` |\n| Duration or overlap | `gantt` |\n| A simple chronological list | `timeline` |\n\nUse a `gantt` diagram, not a timeline, when overlap or duration is the lesson.\nPrefer stable diagram syntax that the target platform supports; avoid beta or\nexperimental Mermaid diagram types in public artifacts. Give every diagram a\ncaption that states the claim it makes, and remove any diagram that merely\nrepeats nearby prose.\n\n### 4. Render Mermaid, then repair\n\nWhen the draft contains Mermaid, create a temporary Markdown file and validate\nevery block before showing the draft. Render a diagram as soon as its block is\nwritten, then validate the complete draft again before presenting it:\n\n```bash\nSCRATCH=\"$(mktemp -d)\"\nnode skills/explain-change/scripts/verify-mermaid.mjs \\\n --input \"$SCRATCH/explainer.md\" > \"$SCRATCH/mermaid-result.json\"\n```\n\nThe helper uses the repository's pinned Mermaid CLI and writes a JSON result\nwith a renderer version, diagram ordinal, source line, and any sanitized error.\nIt skips renderer setup when there are no Mermaid blocks. Do not silently\ninstall a renderer or bypass the browser sandbox: if the renderer is\nunavailable, report the missing prerequisite and treat render verification as\nblocked.\n\nThe verifier normally preserves Chromium's sandbox. Its\n`MERMAID_ALLOW_NO_SANDBOX=1` switch exists solely for this repository's\nintegration tests in an already-isolated CI/container harness; never set it\nwhile creating an explainer or recommend it to readers. If ordinary validation\nrequires that switch, report the sandbox prerequisite as blocked rather than\nweakening the renderer's isolation.\n\nFor a failed diagram, revise only that Mermaid block while preserving its\ntechnical claim, then rerun the helper against the complete draft. Make at\nmost three repair attempts. A timeout, unavailable renderer, unsafe URI,\nunclosed fence, or three failed attempts means the artifact is **not**\nrender-verified: do not show it as a completed draft or post it. Report the\nfailure, the affected diagram, and the next safe action instead.\n\nUse the least-fragile syntax that preserves the lesson. In a sequence diagram,\nprefer participant declarations and message arrows; add `Note` syntax only\nafter the message flow itself renders. Do not assume that a diagram accepted by\none Markdown renderer is accepted by the pinned CLI.\n\nRendering proves compatibility with the committed Mermaid CLI version, not\npixel-identical output on every documentation host. Never enable remote icon\npacks or add remote/executable URIs merely to make a diagram render.\n\n### 5. Draft and verify\n\nUse this shape, adapting detail to the audience:\n\n```markdown\n# : \n\n## The problem\n\n\n## The design in one sentence\n\n\n## The parts that are easy to underestimate\n### \n\n\n## The resulting shape\n\n\n## What is live now\n\n\n## Reading order\n1. `` — \n2. `` — \n\n## Evidence and further reading\n- \n- \n\n## Evidence limits\n- Test evidence: \n- Rollout evidence: \n\n## Diagram verification\n- Mermaid CLI: \n- Result: \n- Attempts: ; correction: \n```\n\nRe-walk the claim ledger before showing the draft:\n\n- [ ] Every factual claim has evidence read or executed during this session.\n- [ ] Every cited file, symbol, test, URL, issue, and revision exists.\n- [ ] The explanation distinguishes evidence, inference, and open questions.\n- [ ] The rollout state is explicit and does not over-claim completeness.\n- [ ] Test-source coverage, executed test results, configuration, and deployed\n state are labeled as distinct evidence levels.\n- [ ] Every Mermaid block rendered successfully with the recorded renderer\n version, or the artifact is explicitly blocked and not presented as complete.\n- [ ] The draft records the Mermaid result, number of attempts, and any\n diagram-only correction; it does not conceal an initial render failure.\n- [ ] The draft contains no secret or sensitive operational data.\n\nShow the draft with its evidence ledger (or an evidence summary for a\nreader-facing artifact). If the user requested posting, ask for confirmation\nafter the final draft, then use their repository/knowledge-base tooling to post\nthe approved text and return the resulting URL.\n\n## Output\n\nReturn an explanation with source links or repository locations, followed by:\n\n```markdown\n## Evidence status\n| Claim | Evidence | Status |\n|---|---|---|\n\n## Open questions\n- \n\n## Evidence limits\n- Test evidence: \n- Rollout evidence: \n\n## Diagram verification\n- Mermaid CLI: \n- Result: \n- Attempts: ; correction: \n\n## Suggested next action\n\n```\n\n## Avoid\n\n- Narrating files changed instead of teaching why the system has this shape.\n- Reading only the local working tree or only the authored change description.\n- Calling a feature complete without checking flags, registrations, and call\n paths.\n- Naming an architectural pattern without checking its defining property.\n- Decorating the explanation with diagrams that encode nothing new.\n- Posting a durable artifact before the user approves the final draft.\n\n---\n**Built by [aictrl.dev](https://aictrl.dev/?utm_source=oss-skills&utm_medium=skill&utm_campaign=explain-change&utm_listing=github-skills&utm_platform=portable&utm_skill=explain-change).** This skill teaches the workflow; aictrl *operationalizes* it — grounded in your backlog, team standards, and codebase knowledge graph. [See how →](https://aictrl.dev/features?utm_source=oss-skills&utm_medium=skill&utm_campaign=explain-change&utm_listing=github-skills&utm_platform=portable&utm_skill=explain-change)\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}