[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6J3YVHHE307AES2XVRXKCER":3,"skill-same:01M6J3YVHHE307AES2XVRXKCER":81},{"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":41,"linkOnly":42,"markdownContent":43,"markdownBody":44,"frontMatter":45,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":14,"repositoryHtmlUrl":49,"repositoryHomepageUrl":6,"ownerHtmlUrl":50,"ownerBlogUrl":6,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6J3YVHHE307AES2XVRXKCER","explain",null,"Explain WHY a piece of code is structured the way it is. Synthesises\narchitectural-memory similar-symbols, git history (blame + commits +\nPR context), AGENTS.md\u002FCLAUDE.md principles, and any plan documents\nthat mention the target. Useful for onboarding (\"why is this here?\"),\ndebugging (\"why is X structured this way and not Y?\"), and refactoring\n(\"can I change this safely or is there hidden context?\").\nPick by INPUT: a TOPIC to survey comes here (\"have we touched rate\nlimiting?\"); a CLAIM to test goes to \u002Finvestigate (\"that landed in July\" —\nit uses --history as one of its instruments). Invoke on the question's\nshape, don't pre-check the target exists first — Step 0 validates it and\nreports cleanly if missing; don't Grep\u002FGlob and answer directly instead.\nTriggers on: \"why is this\", \"explain this code\", \"why does this exist\",\n\"what is this for\", \"\u002Fexplain\", \"give me context on\".\nFull command syntax: see the Usage section in this skill.","Lbstrydom\u002Fclaude-engineering-skills","Lbstrydom","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F77991486?v=4","01M6J3X4N2T0FTZT1RKFXDVS0K","Louis Strydom","01M6J3X4SXV0BXWDMXPW90D8BK",0,"MIT","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fexplain\u002FSKILL.md",[],[5,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40],"syntax","useful","plan documents","invoke","input","full","me","claim","reports","survey","command","question","memory","pick","refactoring","plan","why","git","code","debugging","documents","change","2026-11-10 10:12:30",false,"---\nname: explain\ndescription: |\n  Explain WHY a piece of code is structured the way it is. Synthesises\n  architectural-memory similar-symbols, git history (blame + commits +\n  PR context), AGENTS.md\u002FCLAUDE.md principles, and any plan documents\n  that mention the target. Useful for onboarding (\"why is this here?\"),\n  debugging (\"why is X structured this way and not Y?\"), and refactoring\n  (\"can I change this safely or is there hidden context?\").\n  Pick by INPUT: a TOPIC to survey comes here (\"have we touched rate\n  limiting?\"); a CLAIM to test goes to \u002Finvestigate (\"that landed in July\" —\n  it uses --history as one of its instruments). Invoke on the question's\n  shape, don't pre-check the target exists first — Step 0 validates it and\n  reports cleanly if missing; don't Grep\u002FGlob and answer directly instead.\n  Triggers on: \"why is this\", \"explain this code\", \"why does this exist\",\n  \"what is this for\", \"\u002Fexplain\", \"give me context on\".\n  Full command syntax: see the Usage section in this skill.\n---\n\n# Code Explainer\n\n> **This skill's last line is an end marker naming the skill between em-dashes, after\n> the Reference files table.** If that last line is not in your context (context\n> compaction keeps only the start of a skill), re-read\n> `.claude\u002Fskills\u002Fexplain\u002FSKILL.md` in full before continuing — the later steps still apply.\n\n> **Worktree preflight** — in a linked git worktree the synced tooling tree\n> `scripts\u002F.claude-skills\u002F` is absent — it is gitignored, so `git worktree add`\n> does not populate it, and every command below that uses it dies on a bare\n> `MODULE_NOT_FOUND`. Run `npm run skills:hydrate` first. If this repo defines\n> no such script, `references\u002Fworktree-preflight.md` holds the entry to add — ask\n> the user first, since it edits their `package.json`.\n\n## Usage\n\n```\nUsage:\n  \u002Fexplain \u003Cfile>                       — Explain the file's purpose + history\n  \u002Fexplain \u003Cfile>:\u003Cline>                — Explain a specific line\u002Fsection\n  \u002Fexplain \u003Csymbol-name>                — Find + explain a function\u002Fclass by name\n  \u002Fexplain \u003Cfile>:\u003Cline> --depth=full   — Include full neighbourhood + all blame\n  \u002Fexplain --history \"\u003Ctopic>\"          — \"Did we already solve this?\" — cross-source search\n```\n\nMulti-source synthesiser for \"why is this here?\" questions. Given a\ntarget (file, file:line, or symbol name), gathers context from four\nsources and produces one coherent explanation.\n\n**This skill does NOT modify code.** Read-only — gathers + synthesises.\n\n---\n\n## Step 0 — Parse Target\n\nInput shapes:\n\n| Input | Action |\n|---|---|\n| `\u003Cfile>` (e.g., `scripts\u002Fopenai-audit.mjs`) | Whole-file mode — explain purpose + history |\n| `\u003Cfile>:\u003Cline>` (e.g., `scripts\u002Fopenai-audit.mjs:412`) | Section mode — explain the symbol containing that line |\n| `\u003Csymbol-name>` (e.g., `runMultiPassCodeAudit`) | Symbol mode — find the file:line via architectural-memory + Grep, then explain |\n| `--history \"\u003Ctopic>\"` | **History mode** — \"did we already solve this?\" — jump to §History Mode below; skip Steps 1–5 |\n\nValidate the file exists (file\u002Fsection\u002Fsymbol modes only). If symbol mode\n+ symbol not found, exit with \"Symbol '\u003Cname>' not found in repo via\narchitectural-memory or grep — narrow the query (try `\u003Cfile>:\u003Cline>`).\"\n\n---\n\n## History Mode — `--history \"\u003Ctopic>\"`\n\nWhen the input is `--history \"\u003Ctopic>\"` (e.g. `\u002Fexplain --history \"rate limiting\"`),\nthe question is \"have we touched this before?\" rather than \"why is this here?\"\nSkip the file-shaped Steps 1–5 and run the cross-source aggregator instead.\n\n### Invocation\n\n```bash\nnode scripts\u002Fexplain-history.mjs --topic \"rate limiting\"\n```\n\nOptional flags: `--since \"GIT-SINCE-DATE\"`, `--paths \"CSV-OF-PATHS\"`, `--limit N`.\n\nAdd `--skip-arch` when the cloud is offline or when the user wants\nfaster local-only search.\n\nThe aggregator searches git log (three passes, incl. `-G` so moves are not\nmissed), architectural memory, plan documents and the brainstorm session ledger,\nand returns one JSON document with per-source results plus a chronological\ntimeline. Render it as a Markdown digest: the helper's `summary` verbatim, a\nmost-recent-first timeline, then per-source tables — omit empty source-sections;\nan empty timeline reads \"No prior touches found — this appears to be new ground.\"\n→ `references\u002Fhistory-mode.md` — read when running `--history`, for the source\ndetail, the exact digest template and how to read the result.\n\n**Output rules** — same as §Output rules below: read-only, and every claim in the\ndigest maps to one of the four source sections. Cost: `~$0.0003` for the\narch-memory embedding (skipped when `--skip-arch` or cloud is offline); the other\nthree sources are local-only.\n\n---\n\n## Step 1 — Gather Architectural-Memory Context\n\nIf `cross-skill.mjs` exists in the repo and Supabase is configured:\n\n```bash\n# 1. Near-duplicates and similar symbols\nnode scripts\u002Fcross-skill.mjs get-neighbourhood --json '{\n  \"targetPaths\": [\"\u003Cfile>\"],\n  \"intentDescription\": \"Understand the purpose and shape of \u003Csymbol-or-file>\",\n  \"k\": 6\n}'\n\n# 2. Domain assignment (Plan v6 §2.4 — anchors the explanation in\n#    the architecture map's domain structure)\nnode scripts\u002Fcross-skill.mjs compute-target-domains --json '{\n  \"targetPaths\": [\"\u003Cfile>\"]\n}'\n\n# 3. Caller domains (cross-domain reach detection — Plan v6 §2.4)\nnode scripts\u002Fcross-skill.mjs get-callers-for-file --json '{\n  \"path\": \"\u003Cfile>\"\n}'\n```\n\nUse the result to:\n- Identify **what this symbol does** (the `purposeSummary` of the matching record)\n- Identify **near-duplicates** — sibling symbols solving similar problems\n- Identify **recommended uses** — if the matched record's recommendation is `reuse`, that's a signal this is the canonical version of a pattern\n- Identify **the file's home domain** (from `compute-target-domains.domains[0]`) — emit as `**Domain**: \\`\u003CX>\\`` in the output\n- Identify **cross-domain reach** (from `get-callers-for-file`) — see deterministic spec below\n\n### Cross-domain reach detection (deterministic — Gemini-R2-G3)\n\nLet `homeDomain = compute-target-domains.domains[0]` and `callerDomains\n= get-callers-for-file.callerDomains`. Trigger the \"Cross-domain reach\ndetected\" finding **if and only if all of**:\n\n1. `callerDomains.length > 0` (importers exist)\n2. `nonSelfCallerDomains = callerDomains.filter(d => d !== homeDomain)` has length **> 0** (any external-domain caller is the leak)\n3. `homeDomain` is NOT `null`\u002F`\"unknown\"` AND is NOT in the cross-cutting allowlist: `[\"shared-lib\", \"shared-frontend\", \"core\", \"utils\", \"scripts\"]` (Audit-Gemini-G4: untagged files would otherwise spam false-positive cross-domain warnings on every importer — skip the check entirely when the file's home domain is unknown)\n4. `get-callers-for-file.snapshotProvenance === \"import-graph-populated\"` (skip silently if \"pre-feature-snapshot\" \u002F \"no-active-snapshot\" \u002F \"cloud-disabled\" — false signal otherwise)\n\nWhen triggered, render exactly:\n\n```markdown\n**Cross-domain reach detected**: `\u003ChomeDomain>` file called from\n`\u003CnonSelfCallerDomains[0]>`, `\u003CnonSelfCallerDomains[1]>` (etc) — explain whether this is intentional shared API vs leaked internal.\n```\n\nOmit the section entirely when not triggered.\n\nIf Supabase is offline → skip all three subcommands and note\n`[arch-memory: unavailable]` in the output.\n\n---\n\n## Step 2 — Gather Git History\n\n```bash\nFILE=scripts\u002Flib\u002F*.mjs   # the file you're explaining\nLINE=42                        # the line, if one was specified — omit -L flags otherwise\n\n# Who wrote it + when (last 5 lines of context if line is specified)\ngit blame -L $LINE,+5 \"$FILE\"\n\n# When the file was created + changed (last 10 commits)\ngit log --oneline -10 -- \"$FILE\"\n\n# Recent commits that touched the symbol (if line known)\n# NOTE: use git's native +offset syntax — git does NOT evaluate \"LINE+10\"\n# arithmetic in -L. Pass +10 directly so git computes line + 10 internally\n# (Gemini-R1-G4 fix).\ngit log -L $LINE,+10:\"$FILE\" --oneline | head -10\n\n# PR context (if gh CLI available)\nLAST_COMMIT=$(git log -1 --format=%H -- \"$FILE\")\ngh api \"repos\u002F{owner}\u002F{repo}\u002Fcommits\u002F$LAST_COMMIT\u002Fpulls\" --jq '.[].title' 2>\u002Fdev\u002Fnull\n```\n\nExtract:\n- **Author + date** of the most recent change to this section\n- **Commit message** that introduced the section (often has the WHY)\n- **PR title** if available (often has the requirement \u002F bug context)\n- **Co-evolution** — files frequently changed together (signals coupling)\n\n---\n\n## Step 3 — Find Principle Citations\n\nSearch AGENTS.md, CLAUDE.md, and any docs\u002Fplans\u002F*.md for mentions of:\n- The file path\n- The symbol name\n- Patterns this code uses (e.g., \"single source of truth\", \"graceful degradation\" — these often have explicit citations near the relevant code)\n\n```bash\ngrep -rn \"\u003Csymbol-name>\\|\u003Cfile>\" AGENTS.md CLAUDE.md docs\u002Fplans\u002F 2>\u002Fdev\u002Fnull | head -20\n```\n\nLook specifically for:\n- Plans that planned this code (often explain WHY a particular design)\n- \"Accepted Technical Debt\" entries (explain what compromises were made)\n- \"Do NOT\" rules (explain the discipline being enforced)\n\n---\n\n## Step 4 — Read the Code Itself\n\nRead the target file (or the symbol's enclosing function\u002Fclass). Look for:\n- **Doc comments** — explicit author intent\n- **Type signatures** — what contract is being enforced\n- **Imports** — what this depends on\n- **Surrounding code** — how it's called\n\nFor section mode (file:line): read 30 lines of context around the target line.\n\n---\n\n## Step 5 — Synthesise\n\nProduce a single Markdown response with these sections (omit any that\nhave no data):\n\n```markdown\n## What it is\n\nOne sentence describing the symbol\u002Ffile purpose.\n\n## Why it exists (history)\n\n- Created **YYYY-MM-DD** by **\u003Cauthor>** in commit `abc1234` (\"commit message\")\n- Most recent substantive change: **YYYY-MM-DD** by **\u003Cauthor>** (\"commit message\")\n- Originating PR: #N \"\u003Ctitle>\" (if known)\n- Co-evolved with: \u003Cfiles frequently changed together>\n\n## Why this shape (architectural context)\n\n- Plan: `docs\u002Fplans\u002F\u003Cplan-file>.md` motivated this design (cite the relevant section)\n- Principle citations from AGENTS.md \u002F CLAUDE.md: \u003Clist>\n- Architectural-memory ranking: this is the **canonical** version of \u003Cpattern> \u002F OR a **sibling** to \u003Cother symbols>\n- Accepted technical debt: \u003Crelevant entries from AGENTS.md \"Accepted Technical Debt\">\n\n## Near-duplicates \u002F related code\n\nIf architectural-memory found similar symbols, list them with similarity scores:\n\n| Sim | Symbol | Path | Purpose |\n|---|---|---|---|\n| 0.85 | `\u003Cother>` | `path:line` | \u003Cpurpose> |\n\nNote explicitly whether this is the canonical version or an alternate.\n\n## Safe-change advice\n\nBased on coupling + plan + principles:\n- **Safe to change** (low coupling, no plan citations) — list any tests that will catch regressions\n- **Change with care** (cited in plan, has near-duplicates) — list the plan section to update + sibling symbols to reconcile\n- **Do not change without re-planning** (load-bearing per plan, frequently co-changed with multiple files) — recommend running `\u002Fplan` for the proposed change first\n\n## Sources used\n\n- arch-memory: \u003Cyes\u002Fno>\n- git blame: \u003CN lines>\n- git log: \u003CN commits>\n- AGENTS.md\u002FCLAUDE.md: \u003CN matches>\n- docs\u002Fplans\u002F*.md: \u003CN matches>\n- file read: \u003Cbytes>\n```\n\nKeep the response under ~600 words. If a section is empty (e.g., no plan\nmentions), omit it rather than padding.\n\n---\n\n## Output rules\n\n- **Read-only** — never edit, never commit, never trigger workflows\n- **Cite sources** — every claim must be traceable to one of the four sources\n- **No speculation** — if the WHY isn't in any source, say \"no recorded reason\" rather than guessing\n- **Useful for next action** — the \"Safe-change advice\" section is the most actionable part; make it specific\n- **Cost is small** — at most 1 architectural-memory consultation (~$0.0003) + git operations (free) + 1 file read\n\n---\n\n## Citing what you found\n\nEvery `file:line` this skill emits is a claim about a moment in history, so\n**pin it to the commit you read it at** — `scripts\u002Fexplain-history.mjs:120 (a4ec98da)`. A\npath alone is durable; a path plus a line is a snapshot that decays silently\ninto a *wrong-but-resolving* reference. Measured: of nine bad claims in one\nverified document, five were correct when written and rotted afterwards.\n\nCite append-newest-first files (`status.md`, changelogs, session logs) **by\nsection header, never by line** — every new entry shifts every earlier line, so\nthose citations begin decaying immediately. Cite an untracked or off-disk path\nas `git show \u003Csha>:\u003Cpath>`; it resolves to nothing for any other reader.\n\n→ `references\u002Fverification-discipline.md` §1.\n\n---\n\n## Reference files\n\nThis skill is a multi-source synthesiser: its evidence comes from the repo +\narchitectural-memory + git, gathered fresh each invocation. The files below\ncover specialised situations — read them when the trigger applies.\n\n| File | Summary | Read when |\n|---|---|---|\n| `references\u002Fhistory-mode.md` | History mode in full — the four sources searched, the Markdown digest template, and how to read the result. | The input is `--history \"\u003Ctopic>\"` — before rendering the aggregator's JSON. |\n| `references\u002Fverification-discipline.md` | Verification discipline — pinned citations, figure provenance, two-direction proof, attribution, consumer-side checks. | Writing any `file:line` citation into the explanation — every one needs the commit it was read at (§1). |\n| `references\u002Fworktree-preflight.md` | Worktree preflight remedy — the skills:hydrate npm script to add when a linked worktree lacks the tooling tree. | A command dies with `MODULE_NOT_FOUND` in a linked worktree AND this repo has no `skills:hydrate` script. |\n\n— end of \u002Fexplain —\n","# Code Explainer\n\n> **This skill's last line is an end marker naming the skill between em-dashes, after\n> the Reference files table.** If that last line is not in your context (context\n> compaction keeps only the start of a skill), re-read\n> `.claude\u002Fskills\u002Fexplain\u002FSKILL.md` in full before continuing — the later steps still apply.\n\n> **Worktree preflight** — in a linked git worktree the synced tooling tree\n> `scripts\u002F.claude-skills\u002F` is absent — it is gitignored, so `git worktree add`\n> does not populate it, and every command below that uses it dies on a bare\n> `MODULE_NOT_FOUND`. Run `npm run skills:hydrate` first. If this repo defines\n> no such script, `references\u002Fworktree-preflight.md` holds the entry to add — ask\n> the user first, since it edits their `package.json`.\n\n## Usage\n\n```\nUsage:\n  \u002Fexplain \u003Cfile>                       — Explain the file's purpose + history\n  \u002Fexplain \u003Cfile>:\u003Cline>                — Explain a specific line\u002Fsection\n  \u002Fexplain \u003Csymbol-name>                — Find + explain a function\u002Fclass by name\n  \u002Fexplain \u003Cfile>:\u003Cline> --depth=full   — Include full neighbourhood + all blame\n  \u002Fexplain --history \"\u003Ctopic>\"          — \"Did we already solve this?\" — cross-source search\n```\n\nMulti-source synthesiser for \"why is this here?\" questions. Given a\ntarget (file, file:line, or symbol name), gathers context from four\nsources and produces one coherent explanation.\n\n**This skill does NOT modify code.** Read-only — gathers + synthesises.\n\n---\n\n## Step 0 — Parse Target\n\nInput shapes:\n\n| Input | Action |\n|---|---|\n| `\u003Cfile>` (e.g., `scripts\u002Fopenai-audit.mjs`) | Whole-file mode — explain purpose + history |\n| `\u003Cfile>:\u003Cline>` (e.g., `scripts\u002Fopenai-audit.mjs:412`) | Section mode — explain the symbol containing that line |\n| `\u003Csymbol-name>` (e.g., `runMultiPassCodeAudit`) | Symbol mode — find the file:line via architectural-memory + Grep, then explain |\n| `--history \"\u003Ctopic>\"` | **History mode** — \"did we already solve this?\" — jump to §History Mode below; skip Steps 1–5 |\n\nValidate the file exists (file\u002Fsection\u002Fsymbol modes only). If symbol mode\n+ symbol not found, exit with \"Symbol '\u003Cname>' not found in repo via\narchitectural-memory or grep — narrow the query (try `\u003Cfile>:\u003Cline>`).\"\n\n---\n\n## History Mode — `--history \"\u003Ctopic>\"`\n\nWhen the input is `--history \"\u003Ctopic>\"` (e.g. `\u002Fexplain --history \"rate limiting\"`),\nthe question is \"have we touched this before?\" rather than \"why is this here?\"\nSkip the file-shaped Steps 1–5 and run the cross-source aggregator instead.\n\n### Invocation\n\n```bash\nnode scripts\u002Fexplain-history.mjs --topic \"rate limiting\"\n```\n\nOptional flags: `--since \"GIT-SINCE-DATE\"`, `--paths \"CSV-OF-PATHS\"`, `--limit N`.\n\nAdd `--skip-arch` when the cloud is offline or when the user wants\nfaster local-only search.\n\nThe aggregator searches git log (three passes, incl. `-G` so moves are not\nmissed), architectural memory, plan documents and the brainstorm session ledger,\nand returns one JSON document with per-source results plus a chronological\ntimeline. Render it as a Markdown digest: the helper's `summary` verbatim, a\nmost-recent-first timeline, then per-source tables — omit empty source-sections;\nan empty timeline reads \"No prior touches found — this appears to be new ground.\"\n→ `references\u002Fhistory-mode.md` — read when running `--history`, for the source\ndetail, the exact digest template and how to read the result.\n\n**Output rules** — same as §Output rules below: read-only, and every claim in the\ndigest maps to one of the four source sections. Cost: `~$0.0003` for the\narch-memory embedding (skipped when `--skip-arch` or cloud is offline); the other\nthree sources are local-only.\n\n---\n\n## Step 1 — Gather Architectural-Memory Context\n\nIf `cross-skill.mjs` exists in the repo and Supabase is configured:\n\n```bash\n# 1. Near-duplicates and similar symbols\nnode scripts\u002Fcross-skill.mjs get-neighbourhood --json '{\n  \"targetPaths\": [\"\u003Cfile>\"],\n  \"intentDescription\": \"Understand the purpose and shape of \u003Csymbol-or-file>\",\n  \"k\": 6\n}'\n\n# 2. Domain assignment (Plan v6 §2.4 — anchors the explanation in\n#    the architecture map's domain structure)\nnode scripts\u002Fcross-skill.mjs compute-target-domains --json '{\n  \"targetPaths\": [\"\u003Cfile>\"]\n}'\n\n# 3. Caller domains (cross-domain reach detection — Plan v6 §2.4)\nnode scripts\u002Fcross-skill.mjs get-callers-for-file --json '{\n  \"path\": \"\u003Cfile>\"\n}'\n```\n\nUse the result to:\n- Identify **what this symbol does** (the `purposeSummary` of the matching record)\n- Identify **near-duplicates** — sibling symbols solving similar problems\n- Identify **recommended uses** — if the matched record's recommendation is `reuse`, that's a signal this is the canonical version of a pattern\n- Identify **the file's home domain** (from `compute-target-domains.domains[0]`) — emit as `**Domain**: \\`\u003CX>\\`` in the output\n- Identify **cross-domain reach** (from `get-callers-for-file`) — see deterministic spec below\n\n### Cross-domain reach detection (deterministic — Gemini-R2-G3)\n\nLet `homeDomain = compute-target-domains.domains[0]` and `callerDomains\n= get-callers-for-file.callerDomains`. Trigger the \"Cross-domain reach\ndetected\" finding **if and only if all of**:\n\n1. `callerDomains.length > 0` (importers exist)\n2. `nonSelfCallerDomains = callerDomains.filter(d => d !== homeDomain)` has length **> 0** (any external-domain caller is the leak)\n3. `homeDomain` is NOT `null`\u002F`\"unknown\"` AND is NOT in the cross-cutting allowlist: `[\"shared-lib\", \"shared-frontend\", \"core\", \"utils\", \"scripts\"]` (Audit-Gemini-G4: untagged files would otherwise spam false-positive cross-domain warnings on every importer — skip the check entirely when the file's home domain is unknown)\n4. `get-callers-for-file.snapshotProvenance === \"import-graph-populated\"` (skip silently if \"pre-feature-snapshot\" \u002F \"no-active-snapshot\" \u002F \"cloud-disabled\" — false signal otherwise)\n\nWhen triggered, render exactly:\n\n```markdown\n**Cross-domain reach detected**: `\u003ChomeDomain>` file called from\n`\u003CnonSelfCallerDomains[0]>`, `\u003CnonSelfCallerDomains[1]>` (etc) — explain whether this is intentional shared API vs leaked internal.\n```\n\nOmit the section entirely when not triggered.\n\nIf Supabase is offline → skip all three subcommands and note\n`[arch-memory: unavailable]` in the output.\n\n---\n\n## Step 2 — Gather Git History\n\n```bash\nFILE=scripts\u002Flib\u002F*.mjs   # the file you're explaining\nLINE=42                        # the line, if one was specified — omit -L flags otherwise\n\n# Who wrote it + when (last 5 lines of context if line is specified)\ngit blame -L $LINE,+5 \"$FILE\"\n\n# When the file was created + changed (last 10 commits)\ngit log --oneline -10 -- \"$FILE\"\n\n# Recent commits that touched the symbol (if line known)\n# NOTE: use git's native +offset syntax — git does NOT evaluate \"LINE+10\"\n# arithmetic in -L. Pass +10 directly so git computes line + 10 internally\n# (Gemini-R1-G4 fix).\ngit log -L $LINE,+10:\"$FILE\" --oneline | head -10\n\n# PR context (if gh CLI available)\nLAST_COMMIT=$(git log -1 --format=%H -- \"$FILE\")\ngh api \"repos\u002F{owner}\u002F{repo}\u002Fcommits\u002F$LAST_COMMIT\u002Fpulls\" --jq '.[].title' 2>\u002Fdev\u002Fnull\n```\n\nExtract:\n- **Author + date** of the most recent change to this section\n- **Commit message** that introduced the section (often has the WHY)\n- **PR title** if available (often has the requirement \u002F bug context)\n- **Co-evolution** — files frequently changed together (signals coupling)\n\n---\n\n## Step 3 — Find Principle Citations\n\nSearch AGENTS.md, CLAUDE.md, and any docs\u002Fplans\u002F*.md for mentions of:\n- The file path\n- The symbol name\n- Patterns this code uses (e.g., \"single source of truth\", \"graceful degradation\" — these often have explicit citations near the relevant code)\n\n```bash\ngrep -rn \"\u003Csymbol-name>\\|\u003Cfile>\" AGENTS.md CLAUDE.md docs\u002Fplans\u002F 2>\u002Fdev\u002Fnull | head -20\n```\n\nLook specifically for:\n- Plans that planned this code (often explain WHY a particular design)\n- \"Accepted Technical Debt\" entries (explain what compromises were made)\n- \"Do NOT\" rules (explain the discipline being enforced)\n\n---\n\n## Step 4 — Read the Code Itself\n\nRead the target file (or the symbol's enclosing function\u002Fclass). Look for:\n- **Doc comments** — explicit author intent\n- **Type signatures** — what contract is being enforced\n- **Imports** — what this depends on\n- **Surrounding code** — how it's called\n\nFor section mode (file:line): read 30 lines of context around the target line.\n\n---\n\n## Step 5 — Synthesise\n\nProduce a single Markdown response with these sections (omit any that\nhave no data):\n\n```markdown\n## What it is\n\nOne sentence describing the symbol\u002Ffile purpose.\n\n## Why it exists (history)\n\n- Created **YYYY-MM-DD** by **\u003Cauthor>** in commit `abc1234` (\"commit message\")\n- Most recent substantive change: **YYYY-MM-DD** by **\u003Cauthor>** (\"commit message\")\n- Originating PR: #N \"\u003Ctitle>\" (if known)\n- Co-evolved with: \u003Cfiles frequently changed together>\n\n## Why this shape (architectural context)\n\n- Plan: `docs\u002Fplans\u002F\u003Cplan-file>.md` motivated this design (cite the relevant section)\n- Principle citations from AGENTS.md \u002F CLAUDE.md: \u003Clist>\n- Architectural-memory ranking: this is the **canonical** version of \u003Cpattern> \u002F OR a **sibling** to \u003Cother symbols>\n- Accepted technical debt: \u003Crelevant entries from AGENTS.md \"Accepted Technical Debt\">\n\n## Near-duplicates \u002F related code\n\nIf architectural-memory found similar symbols, list them with similarity scores:\n\n| Sim | Symbol | Path | Purpose |\n|---|---|---|---|\n| 0.85 | `\u003Cother>` | `path:line` | \u003Cpurpose> |\n\nNote explicitly whether this is the canonical version or an alternate.\n\n## Safe-change advice\n\nBased on coupling + plan + principles:\n- **Safe to change** (low coupling, no plan citations) — list any tests that will catch regressions\n- **Change with care** (cited in plan, has near-duplicates) — list the plan section to update + sibling symbols to reconcile\n- **Do not change without re-planning** (load-bearing per plan, frequently co-changed with multiple files) — recommend running `\u002Fplan` for the proposed change first\n\n## Sources used\n\n- arch-memory: \u003Cyes\u002Fno>\n- git blame: \u003CN lines>\n- git log: \u003CN commits>\n- AGENTS.md\u002FCLAUDE.md: \u003CN matches>\n- docs\u002Fplans\u002F*.md: \u003CN matches>\n- file read: \u003Cbytes>\n```\n\nKeep the response under ~600 words. If a section is empty (e.g., no plan\nmentions), omit it rather than padding.\n\n---\n\n## Output rules\n\n- **Read-only** — never edit, never commit, never trigger workflows\n- **Cite sources** — every claim must be traceable to one of the four sources\n- **No speculation** — if the WHY isn't in any source, say \"no recorded reason\" rather than guessing\n- **Useful for next action** — the \"Safe-change advice\" section is the most actionable part; make it specific\n- **Cost is small** — at most 1 architectural-memory consultation (~$0.0003) + git operations (free) + 1 file read\n\n---\n\n## Citing what you found\n\nEvery `file:line` this skill emits is a claim about a moment in history, so\n**pin it to the commit you read it at** — `scripts\u002Fexplain-history.mjs:120 (a4ec98da)`. A\npath alone is durable; a path plus a line is a snapshot that decays silently\ninto a *wrong-but-resolving* reference. Measured: of nine bad claims in one\nverified document, five were correct when written and rotted afterwards.\n\nCite append-newest-first files (`status.md`, changelogs, session logs) **by\nsection header, never by line** — every new entry shifts every earlier line, so\nthose citations begin decaying immediately. Cite an untracked or off-disk path\nas `git show \u003Csha>:\u003Cpath>`; it resolves to nothing for any other reader.\n\n→ `references\u002Fverification-discipline.md` §1.\n\n---\n\n## Reference files\n\nThis skill is a multi-source synthesiser: its evidence comes from the repo +\narchitectural-memory + git, gathered fresh each invocation. The files below\ncover specialised situations — read them when the trigger applies.\n\n| File | Summary | Read when |\n|---|---|---|\n| `references\u002Fhistory-mode.md` | History mode in full — the four sources searched, the Markdown digest template, and how to read the result. | The input is `--history \"\u003Ctopic>\"` — before rendering the aggregator's JSON. |\n| `references\u002Fverification-discipline.md` | Verification discipline — pinned citations, figure provenance, two-direction proof, attribution, consumer-side checks. | Writing any `file:line` citation into the explanation — every one needs the commit it was read at (§1). |\n| `references\u002Fworktree-preflight.md` | Worktree preflight remedy — the skills:hydrate npm script to add when a linked worktree lacks the tooling tree. | A command dies with `MODULE_NOT_FOUND` in a linked worktree AND this repo has no `skills:hydrate` script. |\n\n— end of \u002Fexplain —\n",{"name":5,"description":7},"main","938efbef34b7c76f0d112f336d1ac4018224d186",".claude\u002Fskills\u002Fexplain","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills","https:\u002F\u002Fgithub.com\u002FLbstrydom","Studying M.Sc Computer Science at Heriot Watt","2026-11-10 15:13:10",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add Lbstrydom\u002Fclaude-engineering-skills --skill explain",{"tool":59,"command":60},"bunx","bunx skills add Lbstrydom\u002Fclaude-engineering-skills --skill explain",{"tool":62,"command":63},"pnpm","pnpm dlx skills add Lbstrydom\u002Fclaude-engineering-skills --skill explain","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fexplain\u002FSKILL.md",true,[67,73,77],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Fhistory-mode.md","REFERENCE","参考文档",3412,"https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fexplain\u002Freferences\u002Fhistory-mode.md",{"path":74,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fverification-discipline.md",28340,"https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fexplain\u002Freferences\u002Fverification-discipline.md",{"path":78,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Fworktree-preflight.md",3413,"https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fexplain\u002Freferences\u002Fworktree-preflight.md",[82,100,111,131,145,180],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":93,"publishedAt":41},"01M6J45X4FDB2AD5BGS4R4QY8X","stated-absent","Negative fixture — the contract's stated string never appears in this file.","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fgate-honesty\u002Fnegative\u002Fstated-absent\u002Fskills\u002Fstated-absent\u002FSKILL.md",[88],{"categoryNo":89,"categoryName":90,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000037","律师与法务","PROFESSION","适用职业",[94,95,96,97,98,99],"stated absent","STRING","contract","fixture","never","file",{"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":107,"publishedAt":41},"01M6J45TAX2PPHETZ5TJZG20QQ","nonexistent-implementation","Negative fixture — contract references an implementation file that does not exist.","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fgate-honesty\u002Fnegative\u002Fnonexistent-implementation\u002Fskills\u002Fnonexistent-implementation\u002FSKILL.md",[106],{"categoryNo":89,"categoryName":90,"taxonomyType":91,"taxonomyTypeDesc":92},[108,109,110,96,97,99],"implementation","nonexistent implementation","references",{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":122,"publishedAt":41},"01M6J45P5GN52YFMZ81T7NN1VF","document-only-with-params","Negative fixture — a document-only gate illegally carries params (schema must refuse this fake-check pattern).","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fgate-honesty\u002Fnegative\u002Fdocument-only-with-params\u002Fskills\u002Fdocument-only-with-params\u002FSKILL.md",[117],{"categoryNo":118,"categoryName":119,"taxonomyType":120,"taxonomyTypeDesc":121},"01JBSEEDCAT000000000000002","文档处理","SCENARIO","使用场景",[123,124,125,126,127,128,129,130,97],"only","document","with","document only with params","check","schema","gate","pattern",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":140,"publishedAt":41},"01M6J45J1CCZ7AXDGQKBA9VC8M","lying-skill","Fixture skill for the gate-honesty self-check — every gate here is deliberately dishonest.","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fgate-honesty\u002Flying-skill\u002Fskills\u002Flying-skill\u002FSKILL.md",[137],{"categoryNo":138,"categoryName":139,"taxonomyType":120,"taxonomyTypeDesc":121},"01JBSEEDCAT000000000000023","Skill与智能体开发",[141,127,129,142,143,97,144],"lying skill","fixture skill","self","for",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":160,"publishedAt":41},"01M6J45CW0DNN7K2W39E3PQHEY","visual-audit","Math-first, deterministic visual\u002Fpaint inspection — the 4th UX lens, complementing\npersona-test (journey), click-test (page), and nav-audit (system). Drives Playwright +\ncomputed styles + bounding boxes + CDP forced-pseudo-state to audit declared-token\nconformance, light\u002Fdark theme parity, layout physics, and affordance signifiers. A VLM\nis advisory-only and never gates. CI gate is drift-only on the changed contracted surface.\nTriggers on: \"visual audit\", \"check styling consistency\", \"theme parity\", \"dark mode parity\",\n\"design token drift\", \"paint audit\", \"button\u002Fcard consistency\", \"focus ring audit\",\n\"\u002Fvisual-audit\".","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Fskills\u002Fvisual-audit\u002FSKILL.md",[151,154,157],{"categoryNo":152,"categoryName":153,"taxonomyType":120,"taxonomyTypeDesc":121},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":155,"categoryName":156,"taxonomyType":120,"taxonomyTypeDesc":121},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":158,"categoryName":159,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000032","设计师",[161,162,163,164,165,166,167,168,169,170,171,172,98,123,173,174,175,176,177,178,179],"visual audit","visual","audit","mode","design token","click","inspection","lens","design","ci","persona","math","cdp","journey","drift","focus","physics","layout","card",{"skillNo":181,"name":182,"nameZh":6,"description":183,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":184,"categories":185,"keywords":192,"publishedAt":41},"01M6J4569S40ZASFWW698CHBKP","ux-lock","Generate Playwright e2e specs. Two modes:\n  1. LOCK mode — pin a fix's DOM contract so it doesn't regress (default).\n  2. VERIFY mode — check that a \u002Fplan plan was actually implemented\n     by parsing its Acceptance Criteria section and driving the live URL.\nVERIFY mode grades a plan against a RUNNING app. To judge the plan document\nitself, before anything is built, that is \u002Faudit-plan.\nTriggers on: \"ux lock\", \"lock ux\", \"lock in the fix\", \"write regression spec\",\n\"generate e2e test for\", \"regression test for commit\", \"lock this fix\",\n\"verify the plan\", \"verify plan implementation\", \"check the plan was built\",\n\"audit frontend implementation\", \"did we ship the plan\".\nFull command syntax: see the Usage section in this skill.","https:\u002F\u002Fgithub.com\u002FLbstrydom\u002Fclaude-engineering-skills\u002Fblob\u002Fmain\u002Fskills\u002Fux-lock\u002FSKILL.md",[186,187,190,191],{"categoryNo":152,"categoryName":153,"taxonomyType":120,"taxonomyTypeDesc":121},{"categoryNo":188,"categoryName":189,"taxonomyType":120,"taxonomyTypeDesc":121},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":158,"categoryName":159,"taxonomyType":91,"taxonomyTypeDesc":92},{"categoryNo":89,"categoryName":90,"taxonomyType":91,"taxonomyTypeDesc":92},[193,194,195,164,196,197,198,163,34,199,19,29,200,201,202,203,204,205,206,207,208],"ux lock","lock","ux","commit","generate","acceptance","regression","write","fix","e2e test","default","app","judge","URL","verify plan","frontend"]