Doctrine drift in v1.3.2: incomplete Markdown→YAML migration + skills violating their own stated rules

[danielvm-git]

Summary

bigpowers 1.3.2 is internally inconsistent in several independently checkable ways. The skills and the seed-conventions generator have migrated planning artifacts from Markdown (PLAN.md, STATE.md, …) to YAML (state.yaml, release-plan.yaml, epics/), but the doctrine layer (docs/PRINCIPLES.md, docs/references/gates.md, docs/references/model-profiles.md) was left on the old model. Separately, several skills violate rules the doctrine declares mandatory.

This isn't cosmetic. Found while auditing a real consumer repo whose generated CONVENTIONS.md told the agent to "write a plan to specs/PLAN.md" while every installed skill and the repo itself used YAML shards. Tracing it upstream surfaced the items below.

Version pinned: 1.3.2 (npm install and opensrc fetch agree). Line numbers are from that tag.

---

1. Incomplete Markdown→YAML migration (doctrine still teaches the old artifacts)

The doctrine layer still hard-codes the pre-migration Markdown artifacts as canonical:

• docs/references/gates.md:48,51,53,54,55,65 — Transition gates still require PLAN.md, PROJECT.md, CONTEXT.md, SUMMARY.md, VERIFICATION.md. E.g. :53 "Plan → Build: PLAN.md with runnable verify commands must exist"; :65 "PLAN.md not found. Create it before proceeding."
• docs/PRINCIPLES.md:66 — "Session Governance: Using STATE.md and RELEASE-PLAN.md" (Markdown), while the skills use state.yaml / release-plan.yaml.

Contrast — already migrated:

• seed-conventions/SKILL.md:76,116,156 writes requirements/SCOPE_LATEST.yaml, release-plan.yaml, epics/.
• session-state, plan-work operate on YAML.

Impact: the new generator and the old gates/PRINCIPLES disagree on the canonical artifact names. A downstream-generated CONVENTIONS.md inherited the specs/PLAN.md instruction and contradicted its own YAML workflow — i.e. the contradiction ships to consumers.

Fix: update gates.md + PRINCIPLES.md to the YAML artifact names (or document both, with YAML named as source of truth).

---

2. Skills violate the "SKILL.md < 100 lines" rule (PRINCIPLES anatomy #4 / Ousterhout information-hiding)

docs/PRINCIPLES.md:100 mandates SKILL.md < 100 lines, delegating detail to REFERENCE.md/scripts/. 9 of 61 exceed it:

188  seed-conventions      129  plan-work          105  survey-context
161  develop-tdd           124  investigate-bug    102  using-bigpowers
156  release-branch        104  inspect-quality
151  migrate-spec

Repro:

for f in */SKILL.md; do n=$(wc -l <"$f"); [ "$n" -gt 100 ] && echo "$n $f"; done | sort -rn

The worst offender is seed-conventions (188) — the skill that generates downstream CONVENTIONS.md.

Fix: split overflow into REFERENCE.md, or relax the rule in PRINCIPLES.md to match reality and add a lint check enforcing whatever number you keep.

---

3. docs/references/model-profiles.md is stale (dead skill names + wrong count)

• Cites skills that don't exist in the catalog: refactor-code (:45), debug-error (:46), orchestrate (:88). The catalog has plan-refactor, diagnose-root/investigate-bug, and orchestrate-project.
• model-profiles.md:83 says "expect 58" for grep -rl '^model:' */SKILL.md | wc -l; the actual count is 61.

Fix: regenerate the assignment table from the live catalog; add a CI check that every skill name in model-profiles.md resolves to a directory.

---

4. Skill count is inconsistent across the project's own surface

Source	Count
README badge + body	61
using-bigpowers/SKILL.md:9,98	61
docs/references/model-profiles.md:83	58
actual */SKILL.md	61

(A downstream install surface also showed 65 symlinked skill dirs in ~/.claude/skills, worth reconciling against what the package intends to link.)

For a system whose flagship Akita principle is grep-ability, the catalog can't grep-count itself consistently.

Fix: derive the count at build time from a single source; stop hardcoding it in prose/badges.

---

5. (Minor) "94% quality threshold" has no defined instrument

docs/PRINCIPLES.md:67 and docs/references/gates.md:24 present a 94% quality gate as a hard stop, but no doc defines the scoring function that yields 94 vs 89. As written it reads as an anchor number rather than a measurement.

Fix: point to the .feature/scoring mechanism that actually computes the score, or soften the language to a qualitative gate.

---

Suggested triage (each independently shippable)

• 1. Finish the MD→YAML migration in gates.md + PRINCIPLES.md
• 2. Bring the 9 over-length SKILL.md files under 100 lines (or amend the rule + add a lint)
• 3. Fix model-profiles.md dead skill names + count; add a name-resolves CI check
• 4. Single-source the skill count (README / using-bigpowers / model-profiles)
• 5. Define or soften the 94% threshold

Root cause across 1, 3, 4: facts that should be derived are hardcoded in prose, so they drift the moment the catalog changes. The highest-leverage fix is generating these (artifact names, model table, counts) at build time rather than maintaining them by hand.