mathias
08c935ba8a
superpowers-systematic-debugging restated debug's core (hypothesis before fix) across 296 lines, with a fix-implementation phase that belongs to tdd and a rationalization table that mostly repeats debug's own Anti-Patterns. Two things in it were not restatement, and both are now in debug: instrument every component boundary before hypothesising when a bug spans components, and treat three failed fixes as evidence the mechanism was never identified rather than as a reason to try a fourth. Not deleted with it, contrary to the issue: find-polluter.sh and the three technique files (root-cause-tracing, defense-in-depth, condition-based-waiting) are real assets, one of them an actual tool. They move to debug/references/ with a stated load trigger each, because a reference nobody knows when to open is dead weight. The pressure-test transcripts and CREATION-LOG from the upstream fork go; they document obra's process, not ours. Pressure-tested per #19, and the RED phase refuted the issue's premise. Two subagents without the skill got the multi-component scenario and the four-failed- fixes scenario; both already instrumented boundaries unprompted, and the second refused to write a fifth fix on its own initiative. So these sections are not correcting a demonstrated gap in this model — they are insurance for weaker models and for prompts less well-posed than a test scenario. Recorded as such rather than claimed as a fix. The GREEN run applied both sections correctly and then found four defects in them, all fixed here: the boundary rule read as suspending Iron Law 2's 3-5 hypotheses; the trigger said "reduced" when fixes that change nothing are the stronger signal; "stop proposing a fourth" read as licence to return no hypotheses at all; and the references had no load triggers. Its remaining findings are pre-existing and filed as #36. 41 skills. debug 146 -> 188 lines. Closes #14 Bump-Type: minor
168 lines
11 KiB
Markdown
168 lines
11 KiB
Markdown
# Engineering Skills Index
|
|
|
|
This index lists all available engineering skills. Load the full SKILL.md on demand.
|
|
|
|
The table is **generated** from each skill's frontmatter (`summary`, `use_when`,
|
|
`surfaces`) by `task index`, and `task check` fails if it is out of date. Edit
|
|
the SKILL.md, not the table.
|
|
|
|
<!-- BEGIN skills-table -->
|
|
| Skill | Description | Use when | Surfaces |
|
|
|-------|-------------|----------|----------|
|
|
| `atdd` | Acceptance Test-Driven Development workflow | Feature development with acceptance criteria | claude-code, library |
|
|
| `cad-babysit` | Focused human-in-the-loop session working CAD's stuck queue (read-only) | Picking up whatever `cad stuck` flags, with a human present | claude-code, library |
|
|
| `clean-code` | Clean code principles with Go adaptation | Code review, refactoring, new code | claude-code, library |
|
|
| `code-review` | Code smell detection + Go-specific checklist | Pre-merge review | claude-code, library |
|
|
| `cognitive-load` | Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring | claude-code, library |
|
|
| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious | claude-code, library |
|
|
| `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing | claude-code, library |
|
|
| `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index | claude-code, library, chat |
|
|
| `experiment-spec` | Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature | claude-code, library |
|
|
| `feature-spec` | Implementation-level feature spec (tighter than spec-driven-dev) | Scoping one feature inside an already-specced project | claude-code, library |
|
|
| `gitea-ci` | Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra | claude-code, library |
|
|
| `grill-me` | Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem | Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod | claude-code, library, chat |
|
|
| `own-the-task` | Delegation ownership — Intake → Brief → Plan → Execute | A task is handed over open-ended; \"take this off my plate\"; before a plan exists | claude-code, library, chat |
|
|
| `planning` | Planning and task breakdown | Sprint planning, task decomposition | claude-code, library |
|
|
| `playwright` | Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI | claude-code, library |
|
|
| `problem-analysis` | Deep problem understanding before coding | Starting any non-trivial task | claude-code, library |
|
|
| `refactoring` | Systematic refactoring methodology (Fowler) | When improving existing code | claude-code, library |
|
|
| `regulatory-risk-assessment` | Structured risk register for regulated-industry features | Filing a CAD issue (needs Risk: level); features touching payments, auth, external APIs, user data | claude-code, library |
|
|
| `secret-hygiene` | Stop credentials rendering into the session transcript; safe rotation chain when one leaks | Before any kubectl/SOPS/token command; after a confirmed leak | claude-code, library |
|
|
| `session-retrospective` | Surface non-obvious learnings from a session log | After a coding session ends, before context is lost | claude-code, library |
|
|
| `solid` | SOLID principles with Go examples | Design review, architecture decisions | claude-code, library |
|
|
| `spec-driven-dev` | Spec-driven development for PMs | Writing specs and requirements | claude-code, library |
|
|
| `stage-gate-review` | Stage-gate product governance (go/no-go council) | Preparing a Product Council ask; building a go/no-go checklist; gate review | claude-code, library |
|
|
| `superpowers-brainstorming` | Structured divergent brainstorming | Generating or expanding a set of ideas | claude-code, library |
|
|
| `superpowers-dispatching-parallel-agents` | Fan work out across parallel subagents | Decomposing work for concurrent agents | claude-code, library |
|
|
| `superpowers-executing-plans` | Executing a written plan step by step | Running an approved plan to completion | claude-code, library |
|
|
| `superpowers-finishing-a-development-branch` | Cleanly finishing/landing a dev branch | Wrapping a branch → merge/PR | claude-code, library |
|
|
| `superpowers-receiving-code-review` | Acting on received review feedback | Responding to review comments | claude-code, library |
|
|
| `superpowers-requesting-code-review` | Requesting a code review well | Asking another agent/human to review | claude-code, library |
|
|
| `superpowers-subagent-driven-development` | Subagent-driven development workflow | Building via orchestrated subagents | claude-code, library |
|
|
| `superpowers-using-git-worktrees` | Isolating work with git worktrees | Parallel/isolated work in a worktree | claude-code, library |
|
|
| `superpowers-using-superpowers` | Meta: orienting in the superpowers set | Learning how to use the superpowers skills | claude-code, library |
|
|
| `superpowers-verification-before-completion` | Verify behavior before claiming done | Before marking any task complete | claude-code, library |
|
|
| `superpowers-writing-plans` | Writing implementation plans | Planning substantial work before coding | claude-code, library |
|
|
| `superpowers-writing-skills` | Authoring new SKILL.md skills | Creating a new reusable skill | claude-code, library |
|
|
| `tdd` | Test-Driven Development enforcement | Starting any new feature or fixing a bug | claude-code, library |
|
|
| `telos-load` | Load TELOS intention substrate at session start | Starting any koala session; before architectural decisions; CAD pipeline entry | claude-code, library |
|
|
| `test-design` | Dave Farley test design scoring (Farley Index) | Reviewing or writing tests | claude-code, library |
|
|
| `trainer` | Two-phase brain curation (score candidates, write past quality gate) | Periodic brain pruning and curation | claude-code, library |
|
|
| `user-stories` | Elephant Carpaccio story slicing | Breaking down features | claude-code, library |
|
|
| `web-shot` | Screenshot a running web UI via a koala k3s Playwright job | Visual verification of a running UI when no local browser exists | claude-code, library |
|
|
<!-- END skills-table -->
|
|
|
|
## Wiring into tools
|
|
|
|
This repo is the canonical home, and it is delivered two different ways.
|
|
|
|
### Claude Code — install the plugin
|
|
|
|
This repo hosts a marketplace containing exactly one plugin: itself. The plugin
|
|
carries the skills **plus** the `secret-guard` and `pre-task-ritual` hooks and
|
|
the brain/gitea/infra MCP servers — none of which a symlink can deliver.
|
|
|
|
```
|
|
/plugin marketplace add https://git.d-ma.be/mathias/skills.git
|
|
/plugin install skills@mathias
|
|
```
|
|
|
|
Skills are namespaced: `tdd` becomes `skills:tdd`. Updates arrive when
|
|
`.claude-plugin/plugin.json`'s `version` moves, which CI does on every release.
|
|
Remove any leftover `~/.claude/skills/<name>` symlinks from the pre-plugin era —
|
|
plugin skills do **not** override same-named user skills, so leftovers make
|
|
everything load twice.
|
|
|
|
### Crush, Pi, OpenCode — run `install.sh`
|
|
|
|
These have no plugin system, so they get symlinks — but through one managed
|
|
directory, never one link per skill per harness:
|
|
|
|
```
|
|
~/.agents/skills/ (real directory; Pi reads it directly)
|
|
~/.agents/skills/tdd -> $SKILLS_CHECKOUT_DIR/skills/tdd
|
|
~/.agents/skills/xlsx -> $SKILLS_EXTRA_SOURCES entry
|
|
~/.config/crush/skills -> ~/.agents/skills
|
|
~/.config/opencode/skills -> ~/.agents/skills
|
|
```
|
|
|
|
Total links are N + one per harness. `SKILLS_EXTRA_SOURCES` (colon-separated
|
|
directories) lets a second library — Anthropic's official set, for instance —
|
|
live alongside this one instead of being displaced by it; name collisions are
|
|
logged rather than silently resolved, and the checkout wins (#27).
|
|
|
|
```
|
|
curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
|
|
```
|
|
|
|
`SKILLS_CHECKOUT_DIR` defaults to `~/.local/share/skills` and **must stay
|
|
outside `~/dev`**. On this fleet `~/dev` is an iCloud folder shared by both
|
|
Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala);
|
|
a checkout there means a git working tree with two concurrent writers, and any
|
|
absolute link stored there is broken on one side by construction. See #23.
|
|
|
|
### Check a host
|
|
|
|
`task doctor` (or `bin/doctor`) reports dangling links, links into a source
|
|
nobody configured, skills in the checkout with no link, stray entries, leftover
|
|
Claude symlinks, and a Claude Code plugin sitting on an older generation than
|
|
the host already has. It also runs automatically at session start via the
|
|
plugin, so drift announces itself instead of waiting to be found.
|
|
|
|
## Skill Relationships
|
|
|
|
```
|
|
problem-analysis
|
|
│
|
|
└── user-stories
|
|
│
|
|
├── spec-driven-dev (PM-kickoff lifecycle)
|
|
│ │
|
|
│ ├── feature-spec (per-feature, mid-implementation)
|
|
│ │ │
|
|
│ │ └── planning
|
|
│ │ │
|
|
│ │ └── atdd ──→ tdd (foundation)
|
|
│ │ ├──→ debug (when tests fail)
|
|
│ │ ├──→ clean-code (REFACTOR phase)
|
|
│ │ └──→ test-design (review)
|
|
│ │
|
|
│ └── experiment-spec (research/ML phase, instead of feature-spec)
|
|
│
|
|
└── planning
|
|
|
|
code-review ──→ refactoring ──→ clean-code
|
|
└──→ solid
|
|
|
|
(post-session)
|
|
session-retrospective ──→ trainer ──→ brain (via brain_write)
|
|
|
|
(planning & convergence)
|
|
own-the-task ──→ grill-me (intent first, then stress-test the plan)
|
|
grill-me ──→ planning (after plan is sharpened)
|
|
──→ spec-driven-dev (after hypothesis is validated)
|
|
```
|
|
|
|
## Quick Triggers
|
|
|
|
| Situation | Load |
|
|
|-----------|------|
|
|
| "Build this feature" | `problem-analysis` → `spec-driven-dev` → `planning` → `atdd` |
|
|
| "Fix this bug" | `tdd` |
|
|
| "Review this code" | `code-review` |
|
|
| "Refactor this" | `refactoring` + `clean-code` |
|
|
| "Design this system" | `solid` + `problem-analysis` |
|
|
| "Break this down into stories" | `user-stories` |
|
|
| "Write a spec" | `spec-driven-dev` |
|
|
| "This code is hard to understand" | `cognitive-load` |
|
|
| "Review these tests" | `test-design` |
|
|
| "Set up CI for this project" | `gitea-ci` |
|
|
| "CI pipeline is failing / not triggering" | `gitea-ci` |
|
|
| "Commit directly to main? Or branch?" | TBD: commit to main unless parallel agents are active (see `gitea-ci` SKILL §Trunk-Based Development) |
|
|
| "Grill me / stress-test this / is this ready?" | `grill-me` |
|
|
| "End of Diamond 1 — should we build this?" | `grill-me` (Full Grill) |
|
|
| "About to promote to pre-prod" | `grill-me` (Pre-mortem) |
|
|
| "Take this off my plate / own this / act as my AI employee" | `own-the-task` |
|
|
| "What are the risks?" / "compliance gate" / "risk register" | `regulatory-risk-assessment` |
|
|
| "Start of session" / "load TELOS" / "what are we optimizing toward?" | `telos-load` |
|