nwave-ai/nw-finalize

NW-FINALIZE: Feature Completion and Archive

Wave: CROSS_WAVE Agent: @nw-platform-architect (default) or specified agent

Overview

Finalize a completed feature: verify all steps done|create evolution document|migrate lasting artifacts to permanent directories|preserve delivery history|remove session-only state. Agent gathers project data|analyzes execution history|writes summaries|migrates|cleans session state.

docs/feature/{feature-id}/ becomes delivery history at finalize. Artifacts with lasting value are also copied to permanent directories, while the complete wave history remains available to the wave matrix.

Usage

/nw-finalize @{agent} "{feature-id}"

Context Files Required

The completion-evidence files are docs/feature/{feature-id}/deliver/roadmap.json (the original project plan) and docs/feature/{feature-id}/deliver/execution-log.json (step execution history).

Pre-Dispatch Gate: All Work Complete

Before dispatching, verify all work is done — prevents archiving incomplete features.

1. Parse execution log — Read docs/feature/{feature-id}/deliver/execution-log.json. Gate: file readable.
2. Verify completeness — Check every step has status DONE. Gate: all steps DONE.
3. Block or proceed — If any step is not DONE, list incomplete steps with current status and halt. If all DONE, proceed to dispatch. Gate: zero incomplete steps before dispatch.

Phases

Phase A — Evolution Document

1. Gather source data — Read execution-log.json + roadmap.json (the step log and plan), and all */wave-decisions.md files. Gate: source files read.
2. Extract key decisions — Pull decisions, issues, and lessons from wave-decisions files. Gate: decisions list assembled.
3. Write evolution doc — Create docs/evolution/YYYY-MM-DD-{feature-id}.md with: feature summary, business context, key decisions, work completed (from execution-log.json), lessons learned, issues encountered, links to migrated permanent artifacts. Gate: file written.

Phase B — Migrate Lasting Artifacts

1. Scan workspace — List all files under docs/feature/{feature-id}/. Gate: file list produced.
2. Match against destination map — For each file, apply the destination map below. Gate: migration plan assembled.
3. Create destination directories — Create any missing permanent directories. Gate: directories exist.
4. Copy files — Copy each matched file to its permanent destination. Gate: all copies verified.
5. Log non-migrated files — Note files retained only in delivery history (not copied). Gate: non-migration list documented.

Destination Map

| Source (temporary workspace) | Destination (permanent) | Condition | |---|---|---| | design/architecture-design.md | docs/architecture/{feature}/ | If exists | | design/component-boundaries.md | docs/architecture/{feature}/ | If exists | | design/technology-stack.md | docs/architecture/{feature}/ | If exists | | design/data-models.md | docs/architecture/{feature}/ | If exists | | design/adrs/ADR-*.md | docs/adrs/ | Flat namespace, cross-feature | | distill/walking-skeleton.md | docs/scenarios/{feature}/ | Walking skeleton specification | | discuss/journey-*.yaml | docs/ux/{feature}/ | If UX journeys exist | | discuss/journey-*-visual.md | docs/ux/{feature}/ | If UX visuals exist |

Research docs (docs/research/) are already in a permanent location — no migration needed.

What NOT to Copy to Permanent Destinations

These are process scaffolding. They remain in delivery history but are not copied elsewhere:

| File pattern | Why not copied | |---|---| | deliver/execution-log.json | Audit trail — captured in evolution doc | | deliver/roadmap.json | Step plan — superseded by evolution doc + git history | | deliver/.develop-progress.json | Resume state — temporary | | design/review-*.md | Review findings captured in evolution doc | | discuss/dor-checklist.md | Process gate, not lasting value | | discuss/shared-artifacts-registry.md | Process scaffolding | | discuss/prioritization.md | Superseded by roadmap execution | | */wave-decisions.md | Key decisions extracted into evolution doc |

Phase C — Preserve History and Clean Session State

1. List session artifacts — List only session markers and temp files proposed for removal. Gate: exact list produced.
2. Present for approval — Show the exact removal list to the user and request approval. Gate: user explicitly approves.
3. Preserve delivery history — docs/feature/{feature-id}/ is NOT deleted. The wave matrix derives status from this directory. Removing it would make finalized features disappear from the matrix. The evolution doc in docs/evolution/ is the summary; the feature directory is the history. Gate: directory and wave artifacts preserved.
4. Remove session artifacts only — Remove .nwave/des/deliver-session.json, .develop-progress.json, and approved temp files. Do NOT remove wave artifacts (discuss/, design/, distill/, deliver/). Gate: session markers removed, wave artifacts intact.

NEVER delete without user approval. Show exactly what will be removed.

Phase D — Post-Cleanup Verification

1. Verify migrated files — Confirm every file copied in Phase B exists at its destination. Gate: all destinations present.
2. Update architecture doc statuses — Change any "FUTURE DESIGN" labels to "IMPLEMENTED" in migrated architecture docs. Gate: no stale FUTURE DESIGN labels.
3. Optionally generate reference docs — Invoke /nw-document unless --skip-docs flag provided. Gate: docs generated or skipped.
4. Commit evolution doc and artifacts — Commit 1: evolution doc + migrated artifacts. Gate: commit created.
5. Commit session cleanup — Commit 2: removal of session-only artifacts. Gate: commit created and pushed.

Agent Invocation

@{agent}

Finalize: {feature-id}

Key constraints:

1. Follow the 4-phase process (A → B → C → D) in order.
2. Create evolution document BEFORE migration (needs source files).
3. Migrate BEFORE cleanup (preserves artifacts).
4. Show the session-artifact removal list and wait for user approval before removing anything.
5. Commit and push after approval.

Success Criteria

• [ ] All steps verified DONE before dispatch
• [ ] Evolution document created in docs/evolution/
• [ ] Architecture docs migrated to docs/architecture/{feature}/
• [ ] ADRs migrated to docs/adrs/ (if any)
• [ ] Scenario docs migrated to docs/scenarios/{feature}/ (if any)
• [ ] UX journeys migrated to docs/ux/{feature}/ (if any)
• [ ] User approved removal of session-only artifacts
• [ ] Workspace directory preserved: docs/feature/{feature-id}/
• [ ] Only session markers and approved temp files removed
• [ ] Architecture docs updated to "IMPLEMENTED" status
• [ ] Committed and pushed

Permanent Directory Structure

docs/
  adrs/                  # ADR-NNN-{slug}.md (flat, cross-feature)
  architecture/          # Design docs by feature
    {feature}/
      architecture-design.md
      component-boundaries.md
      data-models.md
      technology-stack.md
  decisions/             # Product decisions by feature (optional)
    {feature}/
  evolution/             # Post-mortem summaries
    YYYY-MM-DD-{feature-id}.md
  research/              # Research docs (flat, cross-feature)
  scenarios/             # Acceptance test documentation by feature
    {feature}/
      walking-skeleton.md
  ux/                    # UX specs and journeys by feature
    {feature}/
      journey-*.yaml
      journey-*-visual.md

Error Handling

| Error | Response | |-------|----------| | Invalid agent name | "Invalid agent. Available: nw-researcher, nw-software-crafter, nw-solution-architect, nw-product-owner, nw-acceptance-designer, nw-platform-architect" | | Missing feature ID | "Usage: /nw-finalize @agent 'feature-id'" | | Project directory not found | "Project not found: docs/feature/{feature-id}/" | | Incomplete steps | Block finalization, list incomplete steps | | No files to migrate | Log "No lasting artifacts found — skipping Phase B" and proceed to session cleanup |

Examples

Example 1: Standard finalization

/nw-finalize @nw-platform-architect "auth-upgrade"

Verifies all steps done. Creates evolution doc. Migrates design/architecture-design.md → docs/architecture/auth-upgrade/, ADRs → docs/adrs/, test-scenarios → docs/scenarios/auth-upgrade/. Shows session artifacts, user approves their removal, and preserves the feature history. Commits.

Example 2: Blocked by incomplete steps

/nw-finalize @nw-platform-architect "data-pipeline"

Pre-dispatch gate finds step 02-03 status IN_PROGRESS. Returns: "BLOCKED: 1 incomplete step - 02-03: IN_PROGRESS. Complete all steps before finalizing."

Next Wave

Handoff To: Feature complete - no next wave Deliverables: docs/evolution/YYYY-MM-DD-{feature-id}.md, migrated artifacts, preserved feature history with session state removed

Expected Outputs

docs/evolution/YYYY-MM-DD-{feature-id}.md
docs/architecture/{feature}/ (migrated design docs)
docs/adrs/ADR-*.md (migrated ADRs)
docs/scenarios/{feature}/ (migrated test scenarios)
docs/ux/{feature}/ (migrated UX journeys, if any)
Preserved: docs/feature/{feature-id}/ (wave history; session artifacts removed)