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.