uclaw-milestone-closed-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# uClaw — Milestone Closed-Loop Discipline

**Why this skill exists**: Bundle 18-27 (2026-05-21) showed how easily
tactical-vs-strategic drift accumulates — 18 PRs in one day, zero
milestone progress. PR #396 settings exposure recovered, but the loss
of 2026-05-21-pr-integration-strategy.md exposed a deeper hole: no
single source of truth for milestone state. This skill encodes the
discipline that closes that loop.

## ⚠️ MUST DO at session start (before any code edits)

```bash
# 1. Read the SSoT — current state of M0-M9
cat docs/superpowers/MILESTONE_STATUS.md | head -40

# 2. Read the strategy doc — methodology + cutoff criteria
cat docs/superpowers/plans/2026-05-22-pr-integration-strategy.md | head -80

# 3. Run drift check — see if previous week is healthy
./scripts/milestone-drift-check.sh --since "1 week ago"
```

If drift check reports RED or YELLOW, **flag it in the first response
to the user**. Don't quietly proceed with tactical work when a YELLOW
or RED alarm is already live.

## The 5-axis closed-loop process

Reference: `docs/superpowers/plans/2026-05-22-pr-integration-strategy.md` §5.

### Per-PR (every PR, < 2 min after merge)

1. **Tag the PR**: every PR title or commit message must carry a milestone
   tag, exactly one of:
   - `[M<N>-T<X>]` — direct task per plan §X.2 (e.g. `[M3-T2]`)
   - `[M<N>-T<X> pilot]` — pilot/types-only (e.g. `[M3-T6 pilot]`)
   - `[M<N>-T<X> wire-up]` — wire-up of an existing pilot (e.g. `[M2-D wire-up]`)
   - `[Slice <N>-<X>]` — bigger wire-up slice (e.g. `[Slice 4-A]`)
   - `[Bundle <N>]` — tactical bug fix / dogfood patch (e.g. `[Bundle 28]`)
   - `[Phase 0.5-T<X>]` — infrastructure work (rare post-2026-05-20)
   - `[Backlog]` — explicit "not in milestone" tag (use sparingly)
2. **Update MILESTONE_STATUS.md**: append PR # to the relevant cell;
   adjust % if the cell changed status. 1-line edit usually enough.
3. **For wire-up / closeout PRs**: think about whether this is M2 / M3 /
   M4 closeout-eligible per §6 cutoff standards. If yes, plan the
   `docs/superpowers/reports/<date>-M<N>-closeout.md` report.

### Per-week (Mondays, < 30 min)

```bash
./scripts/milestone-drift-check.sh --since "1 week ago" --update-status
```

- If YELLOW: leave a NOTE at top of MILESTONE_STATUS.md drift log.
- If RED: STOP. The next thing to do is finish in-flight milestone slice
  before opening any tactical Bundle PR.

### Per-month (month-end audit)

Update `uclaw-upgrade-implementation-plan.md` §34 with month-end snapshot,
bump plan version (v2.4 → v2.5 → ...), close completed milestones into
"Hall of fame" in MILESTONE_STATUS.md, link the closeout report.

## Decision rules (forcing functions)

### Rule 1: PRs that move milestone % MUST update MILESTONE_STATUS.md

The PR is not "done" until that 1-line edit is in. Don't merge a wire-up
PR without it.

### Rule 2: Bundle / Backlog PRs require explicit justification

If you're about to open a Bundle (tactical) PR:

1. Run drift check; if already RED alarm, **don't open it** — finish
   the milestone slice first
2. If GREEN/YELLOW, open it but include in PR description:
   - what it unblocks
   - which milestone it indirectly serves (or "pure dogfood reflex")
3. If 7-day Bundle count is at 5+ already, hard stop until next week
   (or until a wire-up PR ships to reset the counter)

### Rule 3: Spec-first for any wire-up

Before opening a `prep/` branch for wire-up of any M-T pilot:

1. Look for an existing spec in `docs/superpowers/specs/` covering it
2. If absent, write one first (`<date>-<task>-design.md` per the Bundle
   17-B/C example), commit, push — that's its own commit
3. THEN open the prep branch with implementation

Cuts ambiguity, makes review faster, prevents re-litigating design mid-PR.

### Rule 4: Closeout requires a retro

Per strategy §6: a milestone closes only when:
- ADR §16 Exit Criteria ✓
- Plan §X.3 DoD ✓
- Quantitative benchmark data exists
- Closeout report at `docs/superpowers/reports/<date>-M<N>-closeout.md`
- PR description says "Closes M<N>" + links above

## Queue execution (when user says "继续队列下一项" / "next slice" / "queue next")

The closed-loop has a queue artifact at
`docs/superpowers/queue/<phase>-execution-queue.md`. Each queue item is
a self-contained PR with a spec link + branch name + done criteria.

### Procedure when user triggers queue-next

1. Run the queue helper to see state:
   ```bash
   ./scripts/queue-next.sh                 # default: C1
   ./scripts/queue-next.sh C2              # if user specified
   ```
2. The output shows the **next unchecked item** with all its metadata.
3. Read its **Spec** link before any code work.
   - If spec is `_(needs to be written)_`: write the spec FIRST as a
     separate commit, push, **then** return to user for sign-off on

From novolei/uclaw-new, Apache-2.0.

More from novolei/uclaw-new