mcuemcuedocs
Sign in to HubRequest alpha access

A week with mcue

Every other page here explains one command. This one runs a whole week on a single project and shows what each command actually prints. Nothing is elided and nothing is idealised — the Wednesday session gets interrupted, and you can see what that costs in the record.

The project is payments-api. The work is wiring refunds to a ledger service. You can follow along in any directory; nothing here touches your repository.

Monday — register and do the first real session

cd ~/work/payments-api
mcue init payments-api --name "Payments API" --category infrastructure

Identity created: operator you@example.com on machine ed49f65e55866875997784799291f2a8
Project "payments-api" initialized at ~/.mcue/projects/payments-api
anchored at ~/work/payments-api/.mcue

Then you work for four hours. You meant to wire refunds to the ledger. What actually happened is that the ledger client assumes idempotency keys are UUIDs and yours are ULIDs, so every retry double-posts.

At the end of the session:

mcue closeout payments-api \
  --intent "Wire refunds to the ledger" \
  --outcome "Ledger client assumes idempotency keys are UUIDs; ours are ULIDs, so every retry double-posts. Refund path itself is written but unusable until the key format is settled." \
  --blockers "Whether to change our key format or wrap the ledger client" \
  --next-action "Ask Sam which one the ledger team will support" \
  --resume-pointer "internal/ledger/client.go:88, TestRefundRetry fails"

Checkpoint written: ~/.mcue/projects/payments-api/checkpoints/20260817T173512Z.md
Lane: default
Project state refreshed for "payments-api"
Scores: clarity high | cost low | trust medium | quality high (100/100)

closeout takes its five fields as flags. There is no interactive questionnaire — if you would rather write prose in your editor, mcue closeout payments-api --editor opens one, and --intent-from-file and friends read from disk.

Note the last line. The checkpoint is scored as it is written, and this one scores 100 because every field was answered with something a stranger could act on.

Wednesday — resume, then get interrupted

Two days later you have forgotten the specifics. Do not open the editor first:

mcue resume payments-api

# Resume: payments-api

**Lane:** default
**Next:** Ask Sam which one the ledger team will support
**Blockers:** Whether to change our key format or wrap the ledger client
**Resume at:** internal/ledger/client.go:88, TestRefundRetry fails
**Clarity:** high | **Cost:** low | **Fresh:** fresh | **Trust:** medium | **Quality:** high
**Drift:** unknown - no Git repository observer configured

<!-- tokens: ~98/300 -->

That is the default minimal tier — 98 tokens, and it is enough to start. You know the question to ask, the decision that is pending, and the line to open.

Sam says the ledger team will not change the key format. So you write a wrapper. The targeted test passes. Then the checkout incident starts and you are gone for the rest of the day.

The next morning you can record Wednesday honestly, but you cannot claim the work is verified, because you never ran the full suite:

mcue closeout payments-api --degraded \
  --intent "Wrap the ledger client so ULIDs survive a retry" \
  --outcome "Wrapper exists and TestRefundRetry passes, but I was pulled into the checkout incident before running the full suite" \
  --next-action "Run the full payments suite against the wrapper" \
  --resume-pointer "internal/ledger/idempotency.go:24"

Checkpoint written: ~/.mcue/projects/payments-api/checkpoints/20260819T164402Z.md
Lane: default
Project state refreshed for "payments-api"
Scores: clarity high | cost medium | trust low | quality medium (51/100)

This is the part worth reading twice. The same command with --degraded scored 51 instead of 100, dropped trust to low, and raised resume cost to medium. That is not a punishment. It is the record telling the truth about itself, so that future-you does not treat a half-finished session as a finished one.

Inventing "ran the suite, all green" would have scored better and been worth less than nothing.

Friday — the packet warns you before you act

mcue resume payments-api

# Resume: payments-api

**Lane:** default
**Next:** Run the full payments suite against the wrapper
**Blockers:** (none)
**Resume at:** internal/ledger/idempotency.go:24
**Clarity:** high | **Cost:** medium | **Fresh:** fresh | **Trust:** low (degraded, low confidence) | **Quality:** medium
**Drift:** unknown - no Git repository observer configured

<!-- tokens: ~88/300 -->

Trust: low (degraded, low confidence) is the marker doing its job. Before you build on Wednesday's work, the packet has already told you Wednesday was partial.

You run the suite. It is green. You also have a decision worth keeping, so you promote it:

mcue closeout payments-api \
  --intent "Run the full payments suite against the ledger wrapper" \
  --outcome "Suite green. The wrapper normalises ULIDs to the ledger's UUID namespace at the boundary, so retries are idempotent end to end. Sam confirmed the ledger team will not change the key format, which settles Monday's blocker." \
  --next-action "Delete the feature flag and ship the refund path" \
  --resume-pointer "internal/ledger/idempotency.go:24, flag payments.refund_v2" \
  --promotions "Ledger keys stay UUID; we normalise at the boundary rather than changing our ULID format"

Checkpoint written: ~/.mcue/projects/payments-api/checkpoints/20260821T151130Z.md
Lane: default
Project state refreshed for "payments-api"
Scores: clarity high | cost low | trust medium | quality high (85/100)

Trust returns to medium and cost falls back to low. The lane is healthy again because the latest session actually was.

What the week left on disk

ls ~/.mcue/projects/payments-api/

checkpoints
decisions.log
lanes
project_state.md

ls ~/.mcue/projects/payments-api/checkpoints/

20260817T173512Z.md
20260819T164402Z.md
20260821T151130Z.md

Three sessions, three append-only files. The Wednesday one still says what it is:

cat ~/.mcue/projects/payments-api/checkpoints/20260819T164402Z.md

---
project_id: payments-api
lane_id: default
timestamp: "2026-08-19T16:44:02Z"
provenance: human
confidence: low
mode: degraded
quality_score: 51
---
## Intent

Wrap the ledger client so ULIDs survive a retry

## Outcome

Wrapper exists and TestRefundRetry passes, but I was pulled into the checkout incident before running the full suite

## Blockers

(none)

## Next Action

Run the full payments suite against the wrapper

## Resume Pointer

internal/ledger/idempotency.go:24

## Promotion Candidates

(none)

mode: degraded is in the file itself, not in a database somewhere. Friday's promotion landed in its own log:

cat ~/.mcue/projects/payments-api/decisions.log

# Decisions Log: payments-api

## 2026-08-21T15:11:30Z - Promoted from checkpoint

- project_id: payments-api
- source_checkpoint: ~/.mcue/projects/payments-api/checkpoints/20260821T151130Z.md
- lane_id: default
- provenance: human
- confidence: medium
- decision: Ledger keys stay UUID; we normalise at the boundary rather than changing our ULID format

In three weeks, when someone asks why refund keys are normalised at the boundary, that line is the answer and it points at the session that produced it.

Monday again

mcue index

PROJECT              STATUS     LANES NEXT ACTION                              CLARITY  COST     LAST TOUCHED         STALE
---------------------------------------------------------------------------------------------------------------------------
payments-api         active     1     Delete the feature flag and ship the ... high     low      2026-08-21T15:11:30Z

One project, so this is a small table. With fifteen it is the only view that tells you which work has gone quiet — the STALE column fills in for anything you have not touched, and that is usually the thing you were avoiding.

What to take from the week

  • The three closeouts cost about ninety seconds each. The Wednesday resume saved an afternoon of re-deriving Monday's conclusion.
  • The degraded checkpoint is the most valuable one. It is the only record that admits uncertainty, and it is the one that stopped you building on unverified work on Friday.
  • Nothing here required a network, an account, or a running daemon. The whole week is files under $MCUE_HOME.
  • The scores are feedback, not gamification. A closeout that scores badly is usually telling you the next action is not small enough to start cold.

Next