---
name: wrap
description: "Capture and finalize the current Claude session. Writes ## Files touched / ## Decisions made / ## Gotchas surfaced / ## Open questions / ## Next steps into aiwiki/sessions/{date}-{session_id_short}.md, then sets status: done. Use at the natural end of a working session so the next session-start hook can surface a meaningful handoff. Optional argument: a one-line focus statement (otherwise inferred from the active manifest)."
---

# /wrap — Capture and finalize the current session

Finalize this Claude session's handoff artifact. Writes the index sections (Files touched / Decisions / Gotchas / Open questions / Next steps) into `aiwiki/sessions/{date}-{session_id_short}.md` so the next session-start hook can surface a meaningful handoff.

**Distinct from `/dream`:** `/wrap` captures *this session's* knowledge (what was worked on, what was decided). `/dream` consolidates *the whole aiwiki* (merges duplicates, promotes raw → typed). The two can be run sequentially at session end (`/wrap` first, then `/dream`) but they answer different questions.

## Steps

0. **Check aiwiki state.** Read `project.aiwiki_enabled` from `.claude/CLAUDE.md` (treat missing key as `true` for existing projects, explicit `false` or absent `aiwiki/sessions/` directory as disabled). If disabled, surface to the user and stop:
   ```
   aiwiki disabled — /wrap would normally write the session handoff to
   aiwiki/sessions/{date}-{session_id_short}.md. The handoff was NOT saved.
   Options:
     - Re-run /setup and pick Y to enable the knowledge layer for cross-
       session continuity
     - Capture the handoff manually in any external notes tool
   ```
   /wrap exists to feed the SessionStart hook; without aiwiki/sessions/ there is no consumer for the artifact.

1. **Determine session file path.**
   - Read `session_id` from the most recent SessionStart context (Claude Code provides this in the hook payload; if running standalone, ask the user or read from `aiwiki/sessions/*.md` mtime).
   - Path: `aiwiki/sessions/{ISO-date}-{session_id_short7}.md` (the same path pre-compact would have used). If the file already exists (created by pre-compact), append to it. If not, create it lazily here.

2. **Determine focus.**
   - If `/wrap <focus statement>` was supplied, use that.
   - Else: read the active work item from `.forge/work/*/*/manifest.yaml` where `status: in-progress`. Focus = `{type}/{name}` (e.g. `feature/wire-dream`).
   - Else: ask the user "What was this session about?" — one-line answer.

3. **Read the session file** (if it already has content from pre-compact).
   - The `## Checkpoints` section stays as-is — that's event log, not user-facing summary.
   - The index sections (`## Files touched`, etc.) are what you fill.

4. **Capture `## Files touched`.**
   - Run `git diff --name-only $(git merge-base HEAD main)..HEAD` (or `HEAD~10..HEAD` for non-branch work) to find files changed during the session.
   - For each: cite as `[path](path:line)` if a specific line range was the focus; else `[path](path)`.
   - LINT will auto-fill `@<sha7>` on save.
   - Skip generated files, dependency lockfiles, build artifacts.

5. **Capture `## Decisions made`.**
   - List ADRs in `aiwiki/decisions/` written or modified during this session.
   - Format: `- [decision-NNNN: short title](aiwiki/decisions/NNNN-slug.md)`.
   - If none were written but a decision-worthy choice was made conversationally, note: "DEFERRED: {one-line description} — should become an ADR but wasn't written this session."

6. **Capture `## Gotchas surfaced`.**
   - List gotchas in `aiwiki/gotchas/` created or updated this session.
   - Same link format.
   - If a gotcha was hit but not captured, note it as DEFERRED.

7. **Capture `## Open questions`.**
   - List raw notes in `aiwiki/raw/{today}.md` that represent unresolved questions (entries starting with "TBD", "open", "?", or that were /note'd as questions).
   - Format: `- [HH:MM question title](aiwiki/raw/{date}.md#anchor)`.
   - If no /note questions were captured but threads are open, list them as bare bullets.

8. **Capture `## Next steps`.**
   - 2-5 bullets: what the next session should do.
   - Each bullet should reference a file/manifest/issue. No vague "continue working on X."
   - Examples:
     - "Resume `feature/wire-dream` at Phase 6 (slice graph in manifest) — first slice: `wire-pre-compact-hook`."
     - "Review pending dream `aiwiki/proposed/2026-05-18-1742-manual/` before next phase."
     - "Address open question on token rotation policy — see `aiwiki/raw/2026-05-18.md#14-23`."

9. **Update frontmatter.**
   - Set `focus: {focus}` (from Step 2).
   - Set `status: done`.
   - Set `date_end: {today ISO date}`.
   - Set `last_commit: {git rev-parse --short HEAD}` if in a git repo with commits.

10. **Confirm with the user.**
    - Surface the drafted session file content.
    - Ask: "Save this as your session handoff?" — yes / edit / skip.
    - If edit: take inline edits, re-render, ask again.
    - If skip: leave the file's `status: active` (next session-start will surface it as unfinalized).

11. **Save and lint.**
    - Write the file.
    - `wiki-lint` runs automatically on save (PostToolUse hook).
    - If lint surfaces warnings (missing citations, stale `@<sha7>`, etc.), address before considering /wrap complete.

12. **Suggest follow-ups.**
    - If `aiwiki/raw/{today}.md` has unconsolidated entries, suggest: "You have N raw notes from this session — consider `/dream raw` to consolidate before next session."
    - If a pending dream proposal exists in `aiwiki/proposed/`, surface: "N pending dream proposals — review via `forge wiki ui` before next session."

## Example

```
User: /wrap

Agent: Session 2026-05-18-7e8a3f2 (focus: feature/wire-dream).
       Drafted handoff with:
         - 11 files touched (skills/, hooks/, commands/, templates/)
         - 1 decision (consolidate notepad → sessions/)
         - 0 new gotchas this session
         - 2 open questions
         - 4 next-step bullets

       [Renders the proposed file content]

       Save?

User: yes

Agent: Saved aiwiki/sessions/2026-05-18-7e8a3f2.md (status: done).
       Suggestion: 3 raw notes from /note today — consider /dream raw to
       consolidate before next session.
```

## When to use

- **At the natural end of a working session** before exiting Claude Code. Even a 30-second wrap-up preserves the handoff signal.
- **Before a long break** (overnight, end of day). The next session-start surfaces this file so you don't lose context.
- **Before a major context shift** (switching to a different feature mid-day). Wrap the current focus, then start fresh.
- **After a phase locks** if the natural pause is also a session end. (Phase-close already triggers a dream — `/wrap` is the complementary capture for what *you* did, while dream consolidates the *wiki state*.)

## When NOT to use

- **Trivial sessions** (a single read, a one-line edit). No handoff signal — skip /wrap and let the next session-start surface "no recent session" (silence is fine).
- **Mid-task interruptions** where you'll be right back. /wrap is for genuine session boundaries.
- **As a substitute for typed-page writes.** Decisions belong in `aiwiki/decisions/` directly; gotchas in `aiwiki/gotchas/`. /wrap is the *index* of what was written elsewhere — it doesn't replace writing the artifacts themselves.
- **As a substitute for `/dream`.** /wrap captures this session's work; /dream consolidates the whole aiwiki. Use both at the right times.

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | `aiwiki/sessions/` (scaffolded by `/setup`), Claude Code's hook context for `session_id` (or interactive fallback) |
| **Produces** | `aiwiki/sessions/{date}-{session_id_short}.md` with index sections filled and `status: done` |
| **Triggers** | `wiki-lint` PostToolUse hook on save |
| **Feeds into** | `session-start.sh` (next session reads it), `support-dream` (refines on next dream cycle) |

## Do NOT

- Do NOT auto-fire `/dream` from inside `/wrap`. The two are separate concerns; user decides which to run. /wrap can SUGGEST /dream when raw notes accumulated, but does not invoke it.
- Do NOT overwrite the `## Checkpoints` section if pre-compact wrote to it during the session — that's append-only event log, preserved as-is.
- Do NOT write vague prose. Index of links, not narrative. Future sessions follow the links to actual artifacts.
- Do NOT capture every file diff. Skip dependency lockfiles, build artifacts, anything ≤2 lines of cosmetic change. Index the meaningful work.
- Do NOT set `status: done` if the user said "skip" at Step 10 — leave `status: active` so the next session-start surfaces it.