csdlc-retro

CSDLC Retro

Wrap the session by updating NEXT.md in Foundry (status/{username}/next.md or status/next.md for single-user setups). If Foundry is unreachable, write to a local NEXT.md and flag it for sync next session. NEXT.md is a running journal that accumulates — it's not a bootloader that gets rewritten from scratch. The most recent session's work lands on top; prior SHIPPED sections stay in place as historical record.

Before you write

1. get_page('status/next.md') — read the current full contents. You need every prior section because you'll be writing the whole doc back (see safe-write below).
2. Skim your own session transcript for: what shipped, what got filed, decisions locked in, gotchas hit, tech debt added, priority shifts.
3. If the current focus changed this session, note it — the Priority Stack and 🔴 NEXT section both need updating.

NEXT.md structure (the canonical format)

Match what's already there. The format evolved from openclaw and looks like this:

# NEXT.md — What We're Working On

*Updated: <absolute date, e.g. April 9, 2026> (<short session tag>)*

## 🎯 Priority Stack

1. <emoji> **<Project>** — <one-line status or deadline>
2. ...

---

## 🔴 NEXT — <current focus name>

<One-paragraph "why this is the top priority right now">

### <Ticket ID or short name> — <one-line title> (<severity emoji>)

<Repro / context / fix shape in prose, not bullets unless listing files>

### <Next ticket> ...

---

## ✅ SHIPPED — <date> <session tag>

<Session arc in a few sentences: what we tried, what pivoted, what shipped>

### Issues filed
- **#NNN** — <title> (<severity>)

### PR shipped
- **PR #NNN** — <title> — <status>

### Process lessons
- <One-line lesson with concrete trigger, not a platitude>

---

## ✅ SHIPPED — <prior session, PRESERVE as-is>
...

---

## 🟡 ON DECK (No Rush)

### <Project> — <status>
...

---

## 📋 Known Tech Debt

### <Project>
- [ ] <item>
- [x] ~~<completed>~~ — <how it was resolved>

### Process
- [ ] <process-level debt>

Writing rules

• Dates are absolute, never relative. "Yesterday" loses meaning in 48 hours. Use April 9, 2026.
• Emoji per project/section is load-bearing — it's how you scan the doc at a glance. Follow the existing emoji scheme: 🎯 Priority Stack, 🔴 NEXT, ✅ SHIPPED, 🟡 ON DECK, 📋 Tech Debt, and per-project emoji in the Priority Stack.
• Preserve prior SHIPPED sections verbatim. Do not summarize, condense, or delete them. The accumulating log is the point.
• Process lessons are concrete, not platitudes. "Don't refine on top of broken tooling" ✅. "Be careful" ❌. Tie each lesson to the specific thing that triggered it this session.
• Tech Debt uses checkboxes. - [ ] for open, - [x] ~~strikethrough~~ for completed, so you can see progress without losing history.
• Voice: terse, dry, honest. Flag risks, mark slippage ("don't let this slip — 11 days to go"). Matches the rest of the workspace.

How to write it safely (Foundry)

NEXT.md is a single Foundry page. Surgical section-by-section edits work, but the rewrite pattern is preferred for NEXT.md because multiple sections change per update and one atomic rewrite is cleaner than N sequential patches:

1. Compose the full new body as a single markdown string, including every prior SHIPPED section unchanged.
2. delete_doc('status/next.md').
3. create_doc('status/next.md', template='blank').
4. update_section(path='status/next.md', heading_path='# NEXT.md — What We're Working On', content=<full body WITHOUT the H1 — Foundry auto-parses H2+ into children>).
5. get_page('status/next.md') and verify every section is at the right level with no [2] duplicates.

If any step fails, don't retry surgically — re-run the rewrite from step 2.

Edge cases

• Running out of context: Minimum viable update — a new ✅ SHIPPED block (one paragraph) and a refreshed 🔴 NEXT. Leave Priority Stack and Tech Debt untouched. Flag to user that it's abbreviated.
• No prior NEXT.md: First session — write the inaugural version with all sections but only one ✅ SHIPPED block.
• Mid-task, no clean handoff point: Write a Things I'm unsure about subsection inside 🔴 NEXT. Honesty beats fake closure.
• delete_doc unavailable: Fall back to a single update_section on the H1 with the full body (no embedded H1 in content). Verify with get_page twice.
• Priority changed mid-session: Move the new top item to position 1 in Priority Stack, explain why in the ✅ SHIPPED block for this session so the reordering has a paper trail.