toge:handoff

Developer Handoff

This skill turns a working prototype into clean, modular, handoff-ready code that a frontend developer can build production features from without needing to untangle prototype shortcuts.

Input: A completed prototype/ directory Output: The same directory, refactored — no behavior changes, no new features

---

What This Pass Does NOT Do

• Change behavior or interactions
• Add new screens or states
• Fix design decisions
• Replace mock data with real API calls (that's the developer's job)

If something needs to be redesigned, surface it as a comment — don't fix it here.

---

Step 1 — Read Every File First

Before changing anything, read all files in prototype/. Build a mental map of:

• Which components are doing too much
• Where state lives vs. where it's used
• What's prototype-only code (timeouts, fake data inline, console.logs)
• What props/emits are untyped

---

Step 2 — Component Splitting

Split any component where any of these is true:

Signal	Action
Template exceeds ~80 lines	Extract the largest independent section into a child component
Component handles both data orchestration AND rendering	Separate into a container + presentational pair
A template block is repeated 2+ times	Extract into a shared component
A screen has 3+ distinct UI sections	Each section gets its own component

Route/screen-level components (files in screens/) must stay thin — app shell, layout, and feature composition only. Full feature implementations belong in child components.

Naming: PascalCase for components, one clear responsibility per name (PayslipCard, not PayslipCardAndActions).

After splitting, verify the parent passes props down and receives events up. No side effects in presentational components.

---

Step 3 — Composable Extraction

Extract into a composable when:

• The same state or logic is read/written by 2+ components
• A component has side-effect logic (simulated async, filtering, sorting) mixed into its <script setup>
• Mock data is defined inline in the template or script — move it to a composable

Composable rules:

• File: composables/use[Feature].js (or .ts if the project uses TypeScript)
• Always return named reactive state: return { items, isLoading, selectedItem, select }
• Never return raw arrays or plain values — wrap in ref
• Keep composable APIs small: one feature domain per composable

Example extraction:

// Before: inline in screen component
const employees = ref([{ id: 1, name: 'Maria Santos' }])
const isLoading = ref(false)
async function loadEmployees() { ... }

// After: composables/useEmployees.js
export function useEmployees() {
  const employees = ref([{ id: 1, name: 'Maria Santos' }])
  const isLoading = ref(false)
  async function load() { ... }
  return { employees, isLoading, load }
}

---

Step 4 — Type Props and Emits

Every component that receives props or emits events must declare them explicitly.

Props:

<script setup>
// Typed with JSDoc (JS projects)
const props = defineProps({
  employee: { type: Object, required: true },
  isSelected: { type: Boolean, default: false }
})

// Or TypeScript interface (TS projects)
const props = defineProps<{
  employee: Employee
  isSelected?: boolean
}>()
</script>

Emits:

<script setup>
const emit = defineEmits(['select', 'dismiss'])
// or TypeScript:
const emit = defineEmits<{
  select: [employee: Employee]
  dismiss: []
}>()
</script>

Flag any defineProps without types, any $emit calls without a matching defineEmits, and any prop passed via v-bind="$attrs" without inheritAttrs: false.

---

Step 5 — Remove Prototype Artifacts

Scan every file and remove or flag:

Artifact	What to do
console.log(...)	Remove
// TODO, // FIXME, // HACK comments	Remove or resolve — none should survive handoff
setTimeout used only to simulate latency	Keep if it controls a visible loading state; remove if it serves no UX purpose
Hardcoded magic numbers (e.g. setTimeout(fn, 500))	Extract to a named constant at the top of the file: const SUBMIT_DELAY_MS = 500
Commented-out code blocks	Remove
Unused import statements	Remove
Unused ref/reactive declarations	Remove
Inline style hacks (style="...")	Replace with Tailwind classes or token classes

---

Step 6 — Verify File Structure

The final prototype/ directory must follow this structure. Rename or move files that don't fit.

prototype/
├── main.js               ← Stack context comment on line 1
├── App.vue               ← Router root + persistent layout only
├── router.js             ← Named routes, one per screen
├── stores/               ← Pinia stores for cross-screen state only
│   └── use[Feature]Store.js
├── composables/          ← All mock data + reusable logic
│   └── use[Feature].js
├── components/           ← Shared UI used in 2+ screens
│   └── [Feature]/        ← Group by feature, not by type
│       └── [ComponentName].vue
└── screens/              ← One file per route, thin composition surfaces
    ├── 01-[screen].vue
    └── ...

Checks:

• App.vue contains no feature logic — only <RouterView> and persistent shell
• router.js uses named routes with lazy-loaded screen imports
• No screen file contains inline mock data — it lives in composables
• No component is imported but not used

---

Step 7 — Reactivity Audit

• Every value that drives the UI must be a ref or computed — not a plain variable
• Derived values (filtered lists, formatted strings, computed totals) must use computed, not manual watchers
• No watch where computed would do the same job
• No reactive on a single primitive — use ref

---

Step 8 — Product Unit Coverage Check

Before the code quality checklist, verify that the prototype covers everything the product unit required. This is the "did we build it all" gate.

Read the source product unit (UAC, story doc, or feature spec) that was used in Phase 0 to generate the screen spec. Then trace each requirement against the prototype:

Requirement	Source	Screen / Component	Status
Actor: PSI can view payslip summary	UAC §2.1	screens/01-payslip-summary.vue	✅ implemented
Actor: PSI can flag a discrepancy	UAC §2.3	screens/01-payslip-summary.vue → FlagDiscrepancyDrawer.vue	✅ implemented
State: Empty state when no payslips exist	UAC §2.1	components/Payslip/PayslipList.vue	⚠️ missing

Coverage rules:

• Every named actor in the product unit must have at least one screen in the prototype.
• Every functional requirement scoped to the current Bolt/sprint must have a visible implementation (a screen, component, or state that demonstrates it).
• Every state called out in the product unit (empty, error, loading, success, warning) must be designed and present.
• Open design decisions from the ux-screen-spec that have been resolved must be implemented; those that were deferred must be flagged as ⏸️ deferred.

Outcome:

• If any functional requirement is missing (not deferred): mark as ❌ gap. Flag it in the check-in as a blocker — the prototype is incomplete and the gap must be resolved before handoff.
• If any state is missing: mark as ⚠️ missing state. Flag it as a non-blocking gap — include a recommendation for the developer.
• If a requirement was intentionally deferred: mark as ⏸️ deferred and note which sprint/Bolt it belongs to.

Produce the Coverage Table as part of the check-in output.

---

Step 9 — Code Quality Checklist

Run through this before declaring handoff done:

• No component template exceeds ~80 lines
• No screen component owns both state orchestration and multi-section rendering
• All repeated template blocks are extracted
• All mock data lives in composables, not inline
• All defineProps are typed
• All defineEmits are declared
• No console.log, no commented-out blocks, no // TODO
• No unused imports or refs
• No inline style="..." hacks
• App.vue is a thin shell
• router.js uses named lazy routes
• File structure matches the spec above
• Product unit coverage check passed (no ❌ gap items)

---

Check-in

After the pass, present in order:

1. Coverage Table — product unit requirements vs. prototype (from Step 8). Call out any ❌ gap items as blockers.
2. Refactor summary — files changed and what was done (split / extracted / typed / cleaned)
3. Design issues — anything that should go back to the designer before dev picks this up

Then use AskUserQuestion:

"Handoff pass complete. [X/Y requirements covered — N gaps flagged / all requirements covered.] Here's what was refactored: [list]. Any of these changes need a second look before this goes to the dev team?"

If there are ❌ gap items, the question becomes:

"Handoff pass found [N] unimplemented requirements from the product unit: [list]. These need to be designed and implemented before this is dev-ready. Want me to address them now?"

Extract Learnings

After the check-in, call skills/learnings/SKILL.md with the handoff output. Pass the list of splits, extractions, and structural decisions. The skill extracts pattern and convention entries — component boundaries that worked, composable patterns, structural conventions to repeat. Report what was captured inline.