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|clean up temporary workspace. Agent gathers project data|analyzes execution history|writes summaries|migrates|cleans up.

docs/feature/{feature-id}/ is a temporary workspace — it exists during active nWave waves (DISCUSS through DELIVER). At finalize, artifacts with lasting value migrate to permanent directories; the rest is discarded.

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.

• Parse execution log — Read docs/feature/{feature-id}/deliver/execution-log.json. Gate: file readable.
• Verify completeness — Check every step has status DONE. Gate: all steps DONE.
• 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

• Gather source data — Read execution-log.json + roadmap.json (the step log and plan), and all */wave-decisions.md files. Gate: source files read.
• Extract key decisions — Pull decisions, issues, and lessons from wave-decisions files. Gate: decisions list assembled.
• 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

• Scan workspace — List all files under docs/feature/{feature-id}/. Gate: file list produced.
• Match against destination map — For each file, apply the destination map below. Gate: migration plan assembled.
• Create destination directories — Create any missing permanent directories. Gate: directories exist.
• Copy files — Copy each matched file to its permanent destination. Gate: all copies verified.
• Log skipped files — Note any files from the discard list (not migrated). Gate: discard 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 Migrate (Discard)

These are process scaffolding — valuable during delivery, disposable after:

| File pattern | Why discard |

|---|---|

| 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 — Cleanup Workspace

• List remaining files — List all files still in docs/feature/{feature-id}/ after migration. Gate: list produced.
• Present for approval — Show the exact list to the user and request approval. Gate: user explicitly approves.
• Preserve workspace — 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 preserved, session markers removed.
• Clean session artifacts only — Remove .nwave/des/deliver-session.json, .develop-progress.json, and any 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

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

Agent Invocation

@{agent}

Finalize: {feature-id}

Key constraints:

• Follow the 4-phase process (A → B → C → D) in order.
• Create evolution document BEFORE migration (needs source files).
• Migrate BEFORE cleanup (preserves artifacts).
• Show cleanup list and wait for user approval before removing anything.
• 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 cleanup before workspace removal
• [ ] Workspace directory removed: docs/feature/{feature-id}/
• [ ] 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 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 remaining files, user approves, removes workspace. 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, cleaned workspace

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)
Removed: docs/feature/{feature-id}/