agent-wrap-up v6A

Immutable. This exact content is served forever at /api/v1/blob/abb756d808ed5c3c.

---
name: agent-wrap-up
description: Orchestrates the final project state synchronization, including changelog updates, feature documentation, and cross-reference validation.
version: 6
updated: 2026-09-09
---

# Agent Wrap-Up Skill

## Persona
You are the **Lead Context Architect**. Your mission is to ensure that the "Agentic Memory" of this project remains flawless. By the time you finish this skill, any future agent (or human) should be able to pick up exactly where you left off without needing to guess what was changed or why.

## Trigger Conditions
Activate this skill whenever:
1.  A primary development task is completed.
2.  The user says "wrap up", "we're done", "ship it", "archive this", or "good job".
3.  You are closing out a major feature branch or bug fix.

---

## Token Economy & Delegation Model

Wrap-up's token cost is concentrated in *reads* (wiki docs, backlog index), not edits. Two rules keep it lean without losing any benefit.

### Phase-Gating (Skip What Doesn't Apply)
Immediately after Phase 0, triage the diff and declare skips explicitly:
- Diff touches no `src/` files (docs/process-only session) → skip Phases 2–3.
- No plan in `.devops/plans/` was followed this session → skip Phase 4.
- Nothing new surfaced (orphans, debt, backlog matches, tribal knowledge) → skip Phases 5–7 with a one-line declaration in the changelog Why line.
- Phases 0, 1, and 8 are always mandatory.

### Subagent Delegation (Phases 2–7)
Phases 2–7 are read-heavy and parallelizable. On feature-scale sessions, dispatch two subagents **concurrently** after Phase 0. Each prompt must carry the wiki-first mandate (AGENTS.md rule 6) and the agent's exclusive write scope to prevent collisions:

| Agent | Owns (exclusive write scope) | Phases | Returns (summary only — never file contents) |
|-------|------------------------------|--------|----------------------------------------------|
| **A — Wiki Agent** | `.wiki/**` | 2, 3, plus Phase 5 `defer` rows and Phase 7 knowledge-capture | One-line-per-doc summary: created/updated/promoted + stale refs fixed + deviations logged |
| **B — Process Agent** | `.devops/plans/`, `.devops/archive/`, `.devops/backlog/` | 4, 5 (minus `defer` rows), 6 | Counts only: plans archived, backlog entries created/resolved/annotated |

Delegation rules:
- Main agent retains Phases 0, 1 (changelog synthesis from the two returned summaries), and 8.
- Both subagents must follow the `@wiki-writer` discipline for any prose edits they make.
- On small sessions (a handful of files, no plan), running Phases 2–7 inline is acceptable — delegation pays off only when the read surface is large.

---

## Execution Phases

### Phase 0: Mechanical Diff (Evidence, Not Memory)
Before writing anything, establish **what actually changed** — never rely on recall.

1. **Enumerate changed files mechanically**: run `git diff --name-only <last-wrap-up-ref>..HEAD` (use the commit hash of the last wrap-up, or `git log --oneline -1` on `.devops/logs/agent-changelog.md` to find it). If no prior ref exists, diff against the session's starting commit.
2. **Classify each changed file** into a wiki domain: `.wiki/` target (features / components / logic / database / core), `.devops/` process file, or other.
3. **Carry this list into Phases 2 and 3** — it is the authoritative work inventory. Every `src/` file in the diff MUST map to a wiki doc update or an explicit "no doc needed" decision recorded in the changelog entry.

> **Why this phase exists:** wrap-up used to rely on the working agent's memory of "what's new". Memory-based inventories silently drop files, which is how entire feature areas (e.g., the proposals engine suite) went undocumented while lint stayed green.

### Phase 1: The Audit Log (`.devops/logs/agent-changelog.md`)
The changelog records **when and why** — never *what files*. File inventories are derivable from each entry's `ref` commit (`git show --stat <ref>`) and already live in the plan's Completion Note; duplicating them here is what made the log unreadable (2026-09-09 audit: ~42% of its lines were file bullets).

1.  **Add Lean Entry**: Create a new section, **max 5 content lines**:

    ```markdown
    ## YYYY-MM-DD - Short outcome title

    **Why:** [1–3 lines — the decision, the lesson, or the reason it mattered. What changed is implied by the title + ref.]
    **Ref:** `<commit-hash>`
    ```

    - One line per session, not per change: multiple plans closed in one session get one entry naming the theme.
    - No "Files Modified" list, no "Agent" line, no "Database/API Changes: None" filler. Schema changes worth flagging go in the Why line ("added X column; backfill script at …").
    - Deep detail belongs where it already lives: the archived plan (Completion Note) and git history.
2.  **Size check (warning only)**: after adding the entry, check `(Get-Content .devops/logs/agent-changelog.md).Count`. If it exceeds **500 lines**, warn the user in one line — "agent-changelog is over the 500-line guideline (currently _n_ lines); consider archiving old entries manually" — and stop. **Never auto-prune or move entries**: automated pruning was tried on 2026-09-09 and corrupted the log's structure; the cap is a soft guideline enforced by human judgment only.

### Phase 2: Wiki Docs (Reconcile Code Against Spec)
With the spec-first pipeline, docs for planned behavior were already written in parcel Phase 4 (marked `status: in-progress`). Wrap-up **reconciles** rather than retro-documents.

1. **Reconcile against the spec**: for every doc written in parcel Phase 4, verify the implemented code matches the documented behavior and acceptance criteria. Log every deviation in the plan's Completion Note (`Spec Reconciliation`) — then fix the DOC to match reality (the code that shipped is the truth).
2. **Promote**: flip each reconciled doc from `status: in-progress` to `status: stable`. A doc that could not be reconciled stays `in-progress` with a logged deviation — never promote an unreconciled claim.
3. **Cover the leftovers**: review the Phase 0 diff for assets the spec didn't anticipate:
    - New React Hooks (`src/hooks/`)
    - New UI Components (`src/components/`)
    - New Utility Functions (`src/utils/`)
    - New API Routes or Database Collections
4. **Create/Update Docs** for those leftovers: Follow the `@wiki-writer` skill for all wiki prose — read the full target doc first, integrate at the semantically correct section, never append to the end.
    - If a new feature was added: Create a doc in `.wiki/features/<feature-name>.md`.
    - If a component was added: Create/Update `.wiki/components/<component-name>.md`.
    - If logic changed: Update the relevant doc in `.wiki/logic/`.
    - **Standard**: Include inputs (props/params), outputs, side effects, and a brief "Why this exists" section.

### Phase 3: Cross-Reference Synchronization (The "Context Web")
Ensure the rest of the documentation doesn't become "stale" or misleading.

1.  **Search for References**: Use `grep` to find all mentions of the functions, components, or files you modified within the `.wiki/` and `docs/` directories.
2.  **Validate Accuracy**:
    - Does the architecture diagram in `.wiki/core/00-system-index.md` still hold?
    - Do the state shapes in `.wiki/core/04-state-context.md` need updating?
    - Are there "Usage Examples" in other docs that now use an old API signature?
3.  **Update**: Apply surgical edits to ensure every doc reflects the current reality. Where an edit changes prose structure (not a one-line fact fix), follow the `@wiki-writer` discipline: rebalance the affected section so it reads as if written at once.

### Phase 4: Plan Finalization
1.  **Update Implementation Plans**: If you were following a plan in `.devops/plans/`, finalize it in this strict order:
    - **Step 1 — Mark Complete:** Open the plan file and update its **State Dashboard** to set `Status` to `COMPLETE`. Do this **before** moving the file.
    - **Step 2 — Add Completion Note:** At the bottom of the plan, add a `## Completion Note` section explaining the actual outcome and any deviations from the original plan.
    - **Step 3 — Archive:** Move the completed plan file from `.devops/plans/[plan-name].md` to `.devops/archive/[plan-name].md`. Write the updated content to the archive path, then delete the original from `.devops/plans/`.

> **Archival is mandatory, not optional.** A plan that is done but still sitting in `.devops/plans/` is a ghost — it pollutes future agents' context. Every completed plan **MUST** be archived before wrap-up is considered complete.

### Phase 5: Scan for Unfinished Business
Review the session for discoveries that need their own follow-up work. Do not let discovered issues disappear into the archive.

1. **Orphan files / dead code**: If the session found orphan files, dead code, or ghost components, create a backlog plan at `.devops/plans/{code}-{slug}-plan.md` with affected file paths and a terse description. Follow the backlog plan template from the pass-the-parcel skill.
2. **Spaghetti Triage rows**: If the session identified complexity targets (spaghetti smells), dispose each row:
   - `escalate-monster` — flag for the user to invoke `spaghetti-monster` directly
   - `new-parcel` — one backlog plan per row (use same format as step 1)
   - `defer` — log to `.wiki/core/18-knowledge-capture.md` (a `.wiki/` write — Agent A's scope under the Delegation Model)
   - `inline-minor` — confirm resolved in execution trace
3. **Known issues / tech debt**: If any known limitations, workarounds, or debt were accepted during the session, create a backlog entry for each.

### Phase 6: Backlog Triage (`.devops/backlog/backlog-index.md`)
Completed work may resolve one or more open backlog items. Do not skip this phase.

1. **Read the Backlog**: Read `.devops/backlog/backlog-index.md` to see all current entries.
2. **Match Against Completed Work**: Compare each backlog item against what was implemented in this session. An item qualifies for removal if:
   - The feature, fix, or improvement it describes was fully implemented, OR
   - It was explicitly superseded or made irrelevant by the work done.
3. **Take Action**:
   - **Remove** any backlog item that is fully resolved. Delete the entry entirely — do not leave it as a comment or strike-through.
   - **Partially completed** items should have a note appended (e.g., `> Partially addressed by [task name] — remaining: [what's left]`).
   - **Unrelated** items are left untouched.
4. **If no matches found**: State "No backlog items resolved by this session" and move on.

> Always read the full `backlog-index.md` before deciding nothing applies. Backlog items may be described with different wording than the task — match by intent, not by exact name.

### Phase 7: Knowledge Capture & Consolidation
1. **Log Tribal Knowledge**: Review the conversation for any specific user preferences, "gotchas", or architectural decisions that aren't captured in formal documentation but should be remembered. Apply the `@knowledge-capture` **Admission Gate strictly** — only real deviations and valuable tribal knowledge qualify; everything else stays in the plan's Phase 10 log and Completion Note.
2. **Update Decision Log**: Use the `@knowledge-capture` skill to add these entries to the project's `.wiki/core/18-knowledge-capture.md`.
3. **Consolidate (mandatory)**: Run `@knowledge-consolidation` in **tidy mode** (see its Modes table for scope). This is the step that keeps the log lean — skipping it makes KC growth one-way. Full audits are NOT part of wrap-up; they fire only on the consolidation skill's own triggers.

### Phase 8: Coverage Gate (Hard Verification)
Run the mechanical gates. **Wrap-up is not complete until both exit 0.** The gates are cheap (measured <1s each, tiny output) — run them inline in the main context; do NOT delegate them. Use `--quiet` on the lint gate for clean runs.

1. **Doc-graph lint**: `python scripts/wiki_lint.py --quiet` — links, anchors, frontmatter, index completeness. (Omit `--quiet` when diagnosing failures.)
2. **Code-coverage gate**: `python scripts/wiki_coverage_check.py` — every non-test file in `src/utils`, `src/hooks`, `src/components`, `src/views` must be referenced in its domain index. On gaps: add an index row (preferred) or add to the script's `ALLOWLIST` with an explicit reason. Never skip silently.
3. **Stamp freshness**: update the `Last Verified` date in the `.wiki/core/00-system-index.md` Quick Reference for every core doc touched this session.
4. **Machinery version bump**: for each modified file under `.devops/skills/` or `.devops/templates/`, bump its frontmatter `version:` by 1 and refresh `updated:` to today; for each modified file under `scripts/`, `.devops/agents/`, `.devops/rules/`, or `.wiki/rules/`, bump `machinery-version:` once in `.devops/sync-manifest.yaml`. Without this, satellites see `DRIFT` instead of `UPGRADE` on the next `-Check`.
5. **Record the wrap-up ref**: note the current commit hash in the changelog entry so the next Phase 0 diff has a clean baseline.

---

## Mandatory Tools for this Skill
- `grep`: Essential for Phase 3 (finding stale docs).
- Subagent spawn (e.g. `task` / `runSubagent`): required for the Delegation Model on feature-scale sessions.
- `read`: To read existing docs before editing.
- `edit`: For precise updates.

## Non-Negotiable Rules
- **No Placeholders**: Do not say "Update this later". Do it now.
- **Maintain Style**: Match the tone and markdown formatting of existing documentation.
- **Link Integrity**: If you create a new doc, ensure it is linked in the relevant `index.md` (e.g., `.wiki/features/features-index.md`).
- **Coverage Gate is a Hard Stop**: Phase 8 must exit 0 on both scripts before wrap-up is declared complete. A green lint with red coverage is a failed wrap-up.