PLAN: qe style skills — from scaffold to operational /qe:check-style

[mmcky]

Development plan for taking the qe style skills from scaffold (#2, merged) to operational. This is the skills-repo slice of the programme plan — the home of record is QuantEcon/project-style-guide (work plan, proposal issue project-style-guide#6). Rule text is authored only in QuantEcon/style-guide; this repo builds the engine, the skill bodies, and the snapshot mechanism.

Where #2 left us

In place	Pending
/qe:check-style umbrella + 6 thin sub-skills (all marked scaffolding, report "not yet operational")	Everything that makes them operational
qe/references/rules/ — documented location + schema contract	The rendered rules snapshot itself
qe/scripts/ — documented plan (preflight.py, sync-rules.py)	Both scripts
Design invariants encoded: preflight before LLM, report-first, build_risk/RNG never auto-fixed	Report format spec, fix mode

Work items

1. Preflight engine — qe/scripts/preflight.py (can start now)

The deterministic checker. Not blocked on transcription: style-guide already has 5 ratified/POC rules with the fixtures convention exercised (qe-math-002 incl. carve-outs), enough to build the engine against.

• MyST context splitter: classify lecture source into narrative / math environment / code cell / directive (with nesting), so detection regexes run only in their declared context — the zero-false-positive prerequisite
• Rule loader reading schema frontmatter (detection, exclusions, context, build_risk, auto_fix) from references/rules/
• Fixtures runner: pass tests/fixtures/<rule-id>/{correct,incorrect}/ from style-guide; CI job here mirroring the zero-FP gate
• Build-risk trio first as a fast (<1s) gate: align in $$, tick-count nesting, floats inside exercise/solution/prf:
• Expand mechanically as Stage 1 transcription lands upstream

2. Rules snapshot — qe/scripts/sync-rules.py + drift CI (blocked on D8 + render-skill)

• Consume style-guide's render-skill output (to be added upstream, sibling of render-index)
• CI drift check: stale snapshot fails the build (same no-drift guarantee as upstream Phase 0)
• Shape depends on the D8 decision in project-style-guide#6 (private rules DB vs public marketplace: full vendoring / runtime gh fetch / public summaries)

3. Umbrella skill body (can draft now, lands with 1)

• Replace the scaffold procedure with the operational one: resolve lecture(s) from args or branch diff → preflight → category LLM passes → report → fix-on-request
• Report format spec: per-category tables (rule ID, severity, file:line, finding, proposed fix), summary counts, machine-checkable per the audit conventions
• Fix mode: apply only auto_fix: true rules on request; present-but-never-apply for build_risk/RNG rules
• PR mode: scope to lectures changed on the branch; working-copy mode for authors

4. Category passes (blocked on rules coverage per category)

• Port the battle-tested prompts + IMPROVEMENTS.md lessons from action-style-guide into per-category reference material as each category's rules land
• Sub-skills stay thin — confirm each correctly runs the shared procedure restricted to its category

5. Calibration + parity (blocked on 1–4)

• Re-score a sample of the 299 labelled audit.2026-05.style-guide per-lecture reports; agreement with May-2026 scores is the acceptance test (anchor-to-prior-pass)
• Parity run vs action-style-guide on lecture-python-advanced.myst (its one live consumer); the action's comment-triggered workflow retires when the skill dominates

6. Rollout (blocked on 5)

• Version bump + README status flip from "scaffolding"
• Lecture repos opt in: .claude/settings.json (extraKnownMarketplaces + enabledPlugins: {"qe@quantecon": true}); CI example via claude-code-action
• Announce /qe:check-style pre-PR as the recommended author workflow

External blockers (tracked upstream)

Blocker	Where	Gates
Ratify skill family as delivery vehicle	project-style-guide#6 decision 1	everything past item 1
D8: private rules vs public marketplace	project-style-guide#6 decision 2	item 2 shape
Category enum	project-style-guide#2	rule file names + transcription at scale
Stage 1 transcription sprint	style-guide (per the work plan)	items 4–5 coverage

Items 1 and 3 are unblocked today and are the natural next PRs here.

🤖 Generated with Claude Code