docs: reconcile skill catalog with reality, file ADR-0008#11
Draft
cooper (czxtm) wants to merge 2 commits into
Draft
docs: reconcile skill catalog with reality, file ADR-0008#11cooper (czxtm) wants to merge 2 commits into
cooper (czxtm) wants to merge 2 commits into
Conversation
docs/catalog.md advertised 15 skills with no matching skills/<name>/ directory (coding-standards and hl-funding-analysis were deliberately removed in 5347d8d without a catalog update; the rest were never built). Several real skills (brainstorming, using-superpowers, ui-component- architecture) reference these phantom names as prerequisites, so anyone following the catalog would hit a dead end. - Move phantom entries to a "Known gaps" section instead of silently deleting the record that they're referenced elsewhere - Add the real `tdd` skill (was undocumented) and drop the fictional `tdd-workflow` entry, which never existed as a directory - Add skills/README.md (skill format spec), which the root README linked to twice but never existed
This decision has been in effect since 2026-05-22 and was already fully written up as an ADR in the darkmatter/obsidian wiki, but was never filed in this repo's docs/adr/ — the source of truth the wiki explicitly points back to. Org-level instructions (.github CLAUDE.md/AGENTS.md) referenced it only as an unnumbered "OTel-only observability" bullet. Backport the wiki's content here as ADR-0008 so it has one canonical source.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
While importing skills/ADRs from this repo into
darkmatter/.github's org instructions, found thatdocs/catalog.mdhas drifted from the actualskills/directory:skills/<name>/directory (coding-standards,hl-funding-analysiswere deliberately removed in5347d8dwithout a catalog update; the rest —browser-use,caveman,caveman-review,compress,dispatching-parallel-agents,executing-plans,frontend-design,neon-postgres,subagent-driven-development,systematic-debugging,tdd-workflow,verification-before-completion,writing-plans— have no git history at all, i.e. were never built). Several real skills (brainstorming,using-superpowers,ui-component-architecture,vercel-react-best-practices) reference these phantom names as prerequisites/peers, so anyone following the catalog hits a dead end.skills/tdd/directory was undocumented; the catalog instead documented a fictionaltdd-workflow"legacy redirect" that never existed as a directory.skills/README.mdwas linked twice from the rootREADME.mdas "the skill format spec" but never existed.darkmatter/obsidianwiki (as its own0006-decouple-telemetry-concerns.md, accepted 2026-05-22) but never filed in this repo'sdocs/adr/— the source of truth the wiki explicitly points back to. Backported it here.Changes
docs/catalog.md: move the 15 phantom entries to a new "Known gaps" section instead of silently deleting the record that they're referenced elsewhere; add the realtddskill; drop the fictionaltdd-workflowrow; fix dangling precedence-note references.skills/README.md: new — skill format spec (frontmatter,disable-model-invocation,scripts//reference/conventions, validation/cataloging steps).docs/adr/0008-decouple-telemetry-concerns.md: new — backport of the wiki's already-accepted decision.Test plan
bash scripts/validate-skill.shpasses across all skills (unaffected — no skill directories were added/removed, onlyskills/README.md, which the validator correctly skips since it only walks directories)git logthatcoding-standards/hl-funding-analysiswere deliberately removed and the other 13 "known gap" names have no directory history at allGenerated by Claude Code