astrolabe/docs/exploration/skills-repos-review.md

# External skills repos review — mattpocock/skills and github/spec-kit

_Point-in-time record, 2026-07-04. Both repos are shallow-cloned under
`/Users/oleh/code/reference/` (`mattpocock-skills/`, `spec-kit/`) for grepping._

## Question

Do the general-purpose engineering-robustness skill sets — mattpocock/skills and
github/spec-kit — contain anything our project skills (`/alignment`, `/eng-council`,
`/council`, `/doc-update`) should adopt? Constraint: fold single additive ideas into
existing skills; never install a parallel framework.

## Verdict

Neither repo is worth adopting wholesale. Our set covers the same ground with more rigor
because it is project-specific and evidence-grounded where theirs is generic. Four
discrete ideas were folded in (all from mattpocock/skills or shared with spec-kit);
everything else was already covered or rejected.

## The three approaches

- **Ours** — a closed-loop system: `/alignment` enforces numbered project-specific checks
  per diff; `/eng-council` and `/council` review from altitude under a hard evidence
  requirement (file:line, tool output, cited canon); recurring findings promote into
  architecture rules and new alignment checks. Built around the code-leads /
  descriptive-spec regime and a deletion bias (LOC delta per finding).
- **mattpocock/skills** — small composable per-task disciplines: grilling (relentless
  one-question-at-a-time plan interviews), TDD, a bug-diagnosis loop, two-axis code review
  (repo standards + Fowler smell baseline vs. originating spec), domain modeling
  (`CONTEXT.md` glossary + ADRs), deep-module design vocabulary (Ousterhout/Feathers).
  Same anti-framework philosophy as ours; its README positions against spec-kit explicitly.
- **github/spec-kit** — a heavyweight spec-first pipeline (constitution → specify →
  clarify → plan → tasks → analyze → implement → converge), seven-plus artifacts per
  feature, gates between phases. Its thesis — the spec is the primary artifact, code its
  expression — is the inverse of our regime, and it assumes greenfield feature branches,
  team role separation, and business-stakeholder specs. Even `converge`, its only
  code-vs-artifacts mode, treats undocumented code behavior as scope creep to justify or
  remove, where our regime says the code is right and the spec gets rewritten.

## Folded in (2026-07-04)

| Idea                                                                                                                                                                        | Source            | Landed in                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------- |
| Reproduce-before-theorizing debugging discipline: red-capable repro command before any hypothesis; minimize; regression test before fix; prefix-tagged debug logs           | `diagnosing-bugs` | AGENTS.md → AI Developer Protocol |
| Fowler smell baseline as judgement-call heuristics (mysterious name, data clumps, primitive obsession, feature envy, repeated switches, message chains, middle man)         | `code-review`     | `/alignment` rule 4               |
| Tautological-test rule: expected values from an independent source of truth, never recomputed the implementation's way                                                      | `tdd`             | AGENTS.md → Testing Philosophy    |
| The deletion test for suspected pass-throughs: delete the module mentally — complexity vanishing means shallow wrapper, reappearing across callers means it earned its keep | `codebase-design` | `/eng-council` consult mode       |

## Considered and rejected

- **Grilling as a skill** — sessions here are already interactively driven, and the
  harness's question tool plus explore-instead-of-ask covers the discipline. No standing
  gap.
- **`CONTEXT.md` glossary + ADRs (domain modeling)** — `docs/architecture/` +
  `/doc-update` fill the same role with a stricter altitude bar; a second
  decision-record home would split the record.
- **spec-kit's constitution** — SOUL.md + the architecture playbook already are the
  constitution, and ours is enforced mechanically (alignment checks), not re-read per
  phase.
- **spec-kit's "unit tests for English" checklists** (items test requirement quality:
  completeness/clarity/measurability, banned Verify/Test verbs) — the standout idea of
  the repo, but it targets prescriptive specs. Our spec is descriptive; its quality bar
  is "matches the code", which alignment's spec-tracking check already enforces.
- **spec-kit's bidirectional coverage / gap-type taxonomy** (`missing`/`partial`/
  `contradicts`/`unrequested`) — both directions of spec↔code drift are already covered
  by alignment's spec-tracking check and the eng-council Documentation seat.
- **spec-kit's clarify mechanics** (fixed ambiguity taxonomy, Impact×Uncertainty question
  cap, recommend-before-asking) — recommend-before-asking is already harness convention;
  the rest is ceremony sized for teams, not a solo interactive loop.
- **`improve-codebase-architecture` / HTML report** — `/eng-council` sweep covers it with
  real evidence tooling (madge/knip/jscpd) and the metrics trend.
- **`research`, `prototype`, `handoff`** — already covered by reference clones, the
  one-off HTML showcase habit, and harness context management respectively.