porting-handoff

You are entering Phase 4: Handoff for the current milestone.

Locate the agent's artifact directory at <project-root>/.porting/ (defined in porting-methodology). All artifacts live there. Load the porting-methodology skill if not already in context.

Step 1: Prompt Commit

Ask the user to commit any uncommitted work before proceeding:

"Before writing the handoff, please commit any uncommitted changes."

Wait for the user to confirm the commit is done.

Step 2: Update porting-memory.md

Read porting-memory.md from the artifact directory and update it:

Watch List

• Add any unresolved issues, known risks, or critical notes discovered during this milestone that the next session needs to be aware of.
• Remove any items that were resolved during this milestone.
• Keep items concise — one line per item with enough context to understand without reading the full history.

Feature Status

• Update the feature domain table to reflect what was implemented, stubbed, or progressed during this milestone.
• Status values: Not started, Stubbed, Partial, Implemented.
• Add brief notes for domains that changed (e.g., "Implemented — buffer creation, upload via compute encoder").

Curated Knowledge

• Add any important architectural discoveries, engine-specific conventions, or key decisions made during this milestone that would be useful in future sessions.
• Keep the total porting-memory.md under 200 lines. If it's growing too large, compress older notes and move detailed content to separate files in the artifact directory.

Step 3: Write Handoff Note

Determine the current goal name from the goal document (goal-<name>.md). Write a handoff note to the artifact directory as porting-handoff-<goal-name>-M<x>.md (e.g., handoff-basic-rendering-M2.md):

# Handoff: [Milestone Name]

## What Was Done
[One-paragraph summary of the milestone — what was implemented, what's now working]

## Ground Truth Comparison
[Full report of ground truth reference checks performed during validation. For each artifact compared:]
- [Which reference artifact was used (translation-layer capture, RenderDoc XML, etc.)]
- [What was compared (pass structure, draw counts, output textures, resource bindings)]
- [What matched and what diverged]
- [Whether divergences are expected (features not yet implemented) or need investigation]
- [If no ground truths were compared, state why (non-rendering milestone, artifacts unavailable)]

## What's Deferred
[Specific TODOs and STUBs created, with grep patterns]
- `grep "STUB(M<next>)"` — [description of what these stubs are]

## Known Issues
[Bugs, artifacts, validation warnings not yet fixed]

## Watch For
[Things that will trip you up next milestone — specific, actionable warnings]

## Key Decisions Made
[Why something was done a certain way, so the next session doesn't undo it]

## Skills Needed Next
[Which skills the agent should load for the next milestone]

Step 4: Update Goal Document

Read the goal document (goal-*.md in the artifact directory) and update the current milestone's status to "Complete".

Step 5: Notify User

Present a summary of all artifacts created or updated:

## Handoff Summary

### Artifacts Updated
- porting-memory.md — [what changed: watch list items added/removed, feature status updates, knowledge added]
- Handoff note — written to <project-root>/.porting/porting-handoff-<goal-name>-M<x>.md
- Goal document — milestone [name] marked Complete

### Next Milestone
[Name and success criterion of the next milestone, or "All milestones complete — run /porting-plan-goal"]

### Watch List (current state)
[Show the current watch list from porting-memory.md so the user can review]

Step 6: Request Context Reset

After the user has reviewed the handoff summary:

"Milestone complete. Please start a new session for the next milestone."

Do NOT continue working on the next milestone in this session. The one-session-per-milestone model keeps each milestone's changes bounded and reviewable.