Skip to content

docs: spec-prep pre-flight + drive-mill operator skill#1

Merged
bketelsen merged 1 commit into
mainfrom
docs/spec-prep
Jul 24, 2026
Merged

docs: spec-prep pre-flight + drive-mill operator skill#1
bketelsen merged 1 commit into
mainfrom
docs/spec-prep

Conversation

@bketelsen

Copy link
Copy Markdown
Contributor

Documents the new spec-prep pre-flight phase (shipped in `3fc802b`) and adds an operator skill for driving the mill.

Docs site

  • New `concepts/spec-prep.md` — the pre-flight loop: severity-aware convergence (blocking/high resolve; medium/low are recorded, not blockers), the source-grounded hardener, and the `spec_answers.md` / `spec_decisions.json` flow. Leads with a dedicated `spec-prep.svg` diagram in the existing visual language.
  • `how-it-works.md` and `design-rules.md` — reference the pre-flight and the "no blocking findings" bar (why "zero findings" is an asymptote).
  • `reference/cli.md` — documents the previously undocumented `--model=` flag.
  • `reference/concurrency.md` — spec-prep's `.mill-prep` isolation + per-repo guard.
  • `flow.svg` — a small optional "spec-prep" pre-flight hook into `ingest`.

Operator skill

  • New `skills/drive-mill/SKILL.md` — the playbook for taking an issue through the mill: phase decomposition, per-phase re-grounding against merged reality, spec-prep-first (don't hand-edit specs in a loop), the launch recipe, reading the gate signals, handling clarify parks and deadlocks, and the concurrency + installed-engine-drift safety rules. Wired into `install.sh`.

Site builds clean (12 pages); `checks.sh` green; both SVGs well-formed.

🤖 Generated with Claude Code

Site:
- New concepts/spec-prep.md with a dedicated pre-flight loop diagram
  (spec-prep.svg), covering severity-aware convergence, the hardener, and
  the spec_answers.md / spec_decisions.json flow.
- how-it-works and design-rules updated to reference the pre-flight and the
  no-blocking-findings bar; concurrency notes spec-prep's .mill-prep isolation.
- cli.md documents the previously-undocumented --model= flag.
- flow.svg gains a small optional 'spec-prep' pre-flight hook into ingest.

skills/drive-mill: the operator playbook for running the mill — phase
decomposition, per-phase re-grounding, spec-prep-first, the launch recipe,
reading the gate signals, handling clarify parks and deadlocks, and the
concurrency + installed-engine-drift safety rules. Wired into install.sh.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
mill-docs def49e5 Commit Preview URL

Branch Preview URL
Jul 24 2026, 03:37 AM

@bketelsen
bketelsen merged commit 64d34f6 into main Jul 24, 2026
2 checks passed
@bketelsen
bketelsen deleted the docs/spec-prep branch July 24, 2026 03:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant