shipping-and-archiving

name	shipping-and-archiving
description	Use when the user says "done", "ship it", "finish", "complete", "archive", or otherwise indicates the current design is ready to be shipped. Runs final verification (Gate B), archives the CSpec, updates history, extracts a recipe when eligible, and cleans up temp files.

{{ACTIVE_RULES}}

Shipping And Archiving

Overview

Formal completion of a design session. Verifies visual correctness one last time (Gate B), moves the CSpec to specs/shipped/, appends a history entry, and — when the design qualifies — extracts a reusable recipe back into the knowledge base.

When to Use

Invoke when the user:

• says "done", "ship it", "ship", "finish", "complete", "archive"
• has an active CSpec with a snapshot

Do NOT use if:

• the user is still iterating — use generating-figma-design or learning-from-corrections
• the user is abandoning the work — route to drop (handled by using-bridge command map)

Procedure

1. Auto-detect pending corrections

Check if the snapshot has been updated since the last fix run, or if fix was never run:

• If snapshot exists (specs/active/{name}-snapshot.json) AND no learnings reference this spec in learnings.json:

  • Re-extract current Figma state (same extraction as the learning-from-corrections skill, step 2)
  • Compare against snapshot
  • If changes detected:

    Changes detected since last generation/fix.
    Running auto-fix to capture corrections before archiving...
    

    -> Execute the full fix flow via the learning-from-corrections skill (steps 2-10 of its procedure)
  • If no changes: proceed

• If no snapshot exists: skip (design was never generated, spec-only work)

2. Final check

• CSpec exists in specs/active/
• User has validated the design (explicit confirmation)
• If Figma design exists: matches CSpec intent

3. Recipe extraction check

Evaluate if this design qualifies for recipe extraction:

Eligibility criteria (ALL must be met):

1. The CSpec is in screen mode (meta.type: screen)
2. The design was generated and executed in Figma (snapshot exists)
3. Total corrections during the fix cycle <= 2

If eligible:

This design qualifies for recipe extraction.
Creating recipe: {archetype} (from {name})

Extract recipe:

1. Take the final scene graph JSON (post-corrections)
2. Templatize: replace concrete text content with {{ param }} placeholders
3. Replace component keys with @lookup:ComponentName references
4. Define parameters based on variable content (title, items, section count, etc.)
5. Set initial confidence: 0.70 + (0.05 * 1) = 0.75 (first success)
6. Write to recipes/r-{archetype}-{nnn}.json
7. Update recipes/_index.json with the new recipe metadata

If not eligible:

Recipe extraction skipped: {reason}
  (screen mode: {yes/no}, corrections: {n}, threshold: <= 2)

4. Update recipe confidence (if recipe was used)

If a recipe was used during make (check snapshot.meta.recipe):

1. Increment successCount
2. Recalculate confidence:

   base_score = min(1.0, 0.70 + (successCount * 0.05))
   recency_weight = max(0.50, 1.0 - (days_since_last_use * 0.005))
   correction_decay = max(0.60, 1.0 - (avgCorrections * 0.15))
   confidence = base_score * recency_weight * correction_decay
   

3. Update the recipe file and _index.json

5. Archive

mv specs/active/{name}.cspec.yaml specs/shipped/{name}.cspec.yaml

If a snapshot exists:

mv specs/active/{name}-snapshot.json specs/shipped/{name}-snapshot.json

6. Update history log

Append to specs/history.log:

{date} | {name} | {component|screen} | {figma_url} | {learnings_count} | {recipe_extracted: yes/no}

7. Persist learnings summary

Report learnings from this cycle:

Learnings persisted: {n} learnings, {n} flags from this design.
{n} recipe(s) updated, {n} recipe(s) created.

8. Brief retro

• What went well? (patterns to repeat)
• What was friction? (improvements for the workflow)
• What was learned? (reusable knowledge captured in learnings.json)

9. Cleanup

• Delete temp files: /tmp/bridge-scene-{name}.json (if exists)
• Confirm no stale files remain in specs/active/

---

Output

## Done: {name}

Figma: {url}
CSpec archived: specs/shipped/{name}.cspec.yaml
Learnings: {n} persisted
Recipe: {extracted as r-{archetype}-{nnn} | updated {recipe} confidence to {score} | none}

Ready for the next design!

NEVER archive a spec without Gate B evidence from the current or previous turn (fresh screenshot + explicit user confirmation).

NEVER claim "shipped" without the history.log entry being written.

Red Flags

See the full catalog at references/red-flags-catalog.md (repo-root).

Top flags for this skill:

• "User said 'nice', I'll mark it done" → Confirmation must be explicit (done, ship it).
• "I'll skip the recipe extraction, it's a one-off" → Eligibility is deterministic (screen + ≤2 corrections). Let the check run.

Verification

This skill is gated by references/verification-gates.md (repo-root):

• Gate B — mandatory. Fresh screenshot this turn OR in the immediately preceding turn + explicit confirmation text.

Evidence to surface: screenshot tool result, confirmation text, archive path, recipe extraction decision.

Hooks into other skills

(No cross-skill invocations in v6. The docs cascade was removed.)

---

The done gate sequence (decision diagram)

digraph done_gate {
  "User says 'done'" [shape=doublecircle];
  "CSpec in specs/active/?" [shape=diamond];
  "Abort: nothing active" [shape=box style=filled fillcolor=lightcoral];
  "Final compile (Gate B)" [shape=box];
  "Compile exit 0?" [shape=diamond];
  "Take final screenshot" [shape=box];
  "Visual matches intent?" [shape=diamond];
  "Iterate via fix" [shape=box];
  "Move CSpec to shipped/" [shape=box];
  "Recipe eligible?" [shape=diamond];
  "Extract recipe to KB" [shape=box];
  "Append history" [shape=box];
  "Done" [shape=doublecircle style=filled fillcolor=lightgreen];

  "User says 'done'" -> "CSpec in specs/active/?";
  "CSpec in specs/active/?" -> "Abort: nothing active" [label="no"];
  "CSpec in specs/active/?" -> "Final compile (Gate B)" [label="yes"];
  "Final compile (Gate B)" -> "Compile exit 0?";
  "Compile exit 0?" -> "Iterate via fix" [label="no"];
  "Compile exit 0?" -> "Take final screenshot" [label="yes"];
  "Take final screenshot" -> "Visual matches intent?";
  "Visual matches intent?" -> "Iterate via fix" [label="no"];
  "Visual matches intent?" -> "Move CSpec to shipped/" [label="yes"];
  "Move CSpec to shipped/" -> "Recipe eligible?";
  "Recipe eligible?" -> "Extract recipe to KB" [label="yes"];
  "Recipe eligible?" -> "Append history" [label="no"];
  "Extract recipe to KB" -> "Append history";
  "Append history" -> "Done";
}