# Skill: build-complete

End-of-session checklist that closes loops most engineers forget. Updates the changelog, writes what shipped to your state files, reconciles plan drift, captures the decisions worth remembering.

## To install

1. Save this file to `~/.claude/skills/build-complete/SKILL.md`
2. Restart Claude Code
3. Trigger with `/build-complete`, `/bc`, `wrap up`, or `end of session`

---

---
name: build-complete
description: End-of-build checklist. Updates CHANGELOG, state files, PRDs, reconciles plan drift, and lists outstanding actions. Run after any build session that ships features or fixes.
command: bc
---

# Build Complete

## Purpose

Automate the mandatory end-of-session checklist. Every build session that changes shipped behavior runs this before ending. The point is to stop the "what did I actually do today?" pattern and to make sure plan files don't drift silently out of sync with what's actually on disk.

## Trigger

User says `/bc`, `/build-complete`, `wrap up`, `build complete`, or `end of session`.

## Workflow

### Step 1 — Detect what changed

Run `git diff HEAD --stat` and `git log --oneline -1` to understand what was built this session. Read the recent conversation context for the session summary.

If no uncommitted changes and no recent commits from this session, tell the user "nothing to close out" and stop.

### Step 2 — Update CHANGELOG.md

Read the top of `CHANGELOG.md` to see the latest entry format.

Add a new entry at the top:

```
## [YYYY-MM-DD] — <concise title>

### <section>
- bullet point per meaningful change
```

Use today's date. If there's already an entry for today, append a letter suffix (e.g., `2026-04-05b`).

Keep entries concise — what shipped, not how it was built.

### Step 3 — Update state files

Most projects have one or more "state" files at the top level — markdown files that summarize the current shape of a domain (product, sales, ops, marketing, whatever your project's domains are). These complement the CHANGELOG: changelog tracks changes; state files describe the current truth.

Read the relevant state file(s) and add the new entry under "Shipped features (latest first)" or the appropriate section. Update the `_Updated:` date at the top of each modified state file.

**Trim rule:** After writing a new shipped feature entry, count the dated sections under "Shipped features (latest first)". If there are more than 5, delete all sections after the 5th. The oldest entries live in git history. Keep the "Current phase" section and everything above the shipped-features list intact.

### Step 4 — PRD maintenance

If your project keeps PRDs (product requirement docs) in `/docs/`, check whether the build modified behavior covered by any of them.

1. **If PRD exists for this feature:** Add a CHANGELOG entry at the top of the PRD file (date + what changed).
2. **If new feature with no PRD:** Create one if the feature is substantial enough (3+ routes, new data model, or new user-facing workflow). Skip for small fixes.
3. **If a PRD is now fully shipped:** Verify it's marked as shipped in the status field.
4. **Delete stale docs:** If any file in `/docs/` is fully superseded or contains only completed items, delete it.

Output the line: `📄 PRD UPDATED: [filename] — [summary]`

### Step 5 — Co-op plan reconciliation (plan-drift sweep)

Co-op plans are execution journals with `[ ]` / `[x]` checkboxes. Work that ships outside `/co-op next` (which is most of it — most users run `/build-complete` instead) leaves plan files drifting: real files exist on disk against rows that still read `[ ]`. Future sessions then re-do work or brief steps that are already done. This step catches that.

**Run the sweep every time build-complete executes.** Not optional.

1. **List open plans:** `ls plans/co-op/*.md`. Skip any plan whose header marks it `RETIRED`, `SHIPPED`, or `ARCHIVED`.

2. **For each open plan, extract named output paths from every `[ ]` row.** Read the plan, find unchecked rows, and for each row scan for file paths in inline backticks, plain paths, "Output:" / "Write" / "Create" fields, and migration file names.

3. **Check disk for each extracted path** using `ls` / `test -e`. A path that exists against a `[ ]` row = silent ship.

4. **For each silent-ship finding:**
   - Flip `[ ]` → `[x]` on that row
   - Append a `Result:` block citing the file path(s) that proved it shipped, the commit SHA from `git log --follow --oneline <path> | head -1`, and the date
   - Prefix with "Reconciled by build-complete YYYY-MM-DD — " so future sessions know it was a post-hoc reconciliation
   - If the row is *partially* shipped, do NOT flip the checkbox. Inject a sub-status block listing ✅ / ❌ per path. Partial ships get tracked explicitly until they're complete.

5. **Wire-point detection:** if a row mentions "wire into X, Y, Z" with multiple integration points, grep for the core symbol across the codebase and list which wire points have actually been integrated vs pending. Treat as partial ship.

6. **Progress Summary refresh:** after all sweeps, update each plan's `## Progress Summary` block at the top with new done/active/blocked counts.

7. **Report in the final summary** under a new `**Plan drift:**` line: `N rows reconciled across M plans (X silent ships flipped, Y partial ships annotated)` — or `clean, no drift detected`.

**Rules:**
- Never flip a row without disk proof. A `Result:` claim in a sibling row doesn't count.
- Never flip a row where the named path is ambiguous (multiple files could match). Annotate as "needs manual review" and surface in action items.
- If a file exists but looks incomplete (e.g. empty stub, only imports), treat as partial and do NOT flip.
- Do not touch rows marked `[⏸]` (blocked), `[~]` (skipped), or `[→color]` (claimed in team mode).

### Step 6 — Capture lessons

If the user corrected your approach during the session, record the lesson in `tasks/lessons.md` (or wherever your project keeps post-hoc learnings). Create the file if it doesn't exist.

### Step 7 — Persist decisions

Extract decisions and lessons from the current session and write them to your decision log (whatever your project's persistent knowledge layer is — Supabase, SQLite, plain markdown, Notion, your call).

**What to capture:**
- Decisions made (architecture choices, technology decisions, product direction)
- Lessons learned (mistakes corrected, gotchas discovered, patterns that worked)
- Business facts surfaced (metrics, constraints, context relevant to operations)

**Skip:** implementation details, config tweaks, bug fixes without broader lesson, anything already well-documented in code.

The bar for capture: "Would future-you give better advice next week if it knew this?" If no, skip it.

### Step 8 — Push and deploy verification

Check git status and deployment state:

```bash
git log origin/main..HEAD --oneline
git status --short
```

- If unpushed commits exist: list them and add "Push to origin/main" to action items
- If uncommitted changes exist: list them and add "Review uncommitted changes" to action items
- If everything is pushed: confirm "All commits pushed"

If you can hit your deploy provider's API (Vercel, Netlify, Render), check the latest deployment state. Otherwise note "Verify build manually."

Report state as: READY ✓ / BUILDING ⏳ / ERROR ✗

### Step 9 — Output summary

Format the output as:

```
## Build Complete: <title>

**Changelog:** Updated (YYYY-MM-DD entry added)
**State files:** <list of files updated>
**PRD:** <created/updated/none>
**Plan drift:** <N rows reconciled across M plans — or "clean">
**Decisions captured:** N items
**Git:** All pushed / N commits unpushed
**Deploy:** READY ✓ / BUILDING ⏳ / ERROR ✗ / Check manually
**Stale docs deleted:** <list or none>

---
**Action required:**
- [ ] pending action 1
- [ ] pending action 2
---
```

If all commits are pushed and deploy is READY, omit the action required block entirely.

### Step 10 — Copy-paste handoff prompt

**This step is mandatory.** After the summary, emit a fenced code block titled "Handoff prompt for next session" that the user can paste verbatim into a new chat's first message. Self-contained — the next session has zero memory of this conversation.

Format:

```
Context from previous session ({YYYY-MM-DD}):

**What shipped:** {1-3 bullet points — concrete, with commit range or key files}

**What's open:** {numbered list of unfinished items in priority order, with file paths}

**Decisions made:** {any architectural or product decisions the next session must respect}

**Blockers for the user:** {action items waiting on the user, if any}

**Start here:** {exact first action for the next session — file to read, step to execute, or command to run}
```

Rules:
- No prose preamble. Start with the context line.
- Include file paths, not descriptions.
- If a co-op plan is active, include the `/co-op start <path>` command.
- Keep under 300 words.

## Rules

- Never push to git automatically. Only the user pushes. Flag unpushed commits, never push them.
- Never skip the changelog or state file updates.
- Never skip the co-op plan reconciliation sweep — silent drift compounds fast.
- Keep changelog entries concise — what, not how.
- Decision capture is mandatory, not optional — even if only 1 item qualifies.
- An end-of-day synthesis pass across multiple sessions is a separate skill. `build-complete` is per-session primary capture.