dv-breakdown

name	dv-breakdown
description	Da Vinci breakdown direct route skill for Codex.

Da Vinci Breakdown

Use this direct $dv-breakdown skill for the request.

Action: breakdown

Shared hook and lifecycle boundary:

• treat da-vinci workflow-status --project <path> [--change <id>] --json and da-vinci next-step --project <path> [--change <id>] as the single routing brain; do not invent a separate routing or readiness engine
• treat .da-vinci/state/change-state.json, .da-vinci/state/change-seq.json, and .da-vinci/state/change-lifecycle.lock as command-owned lifecycle surfaces, not prompt-owned heuristics
• after those route checks confirm $dv-breakdown, run da-vinci hook-bridge --project <path> [--change <id>] --trigger-kind stage:start --stage breakdown --json
• hook-bridge is bounded to stage:start preflight only; it must not replace manual promotion, route selection, or lifecycle commands
• treat hook requires as same-trigger dependencies only; required consumers block when a dependency is missing, disabled, stale, failed, returns WARN, or is ordered after the consumer, and optional consumers warn and skip execution
• preserve policy order as execution order; do not topologically sort or auto-reorder hook bindings
• treat da-vinci hook-status and workflow-status as read-only hook diagnostics for local binding identity, project declaration/default provenance, snapshot status, role metadata, latest-versus-effective run interpretation, and hookRecovery; they must never become route authority or a second workflow engine
• if .da-vinci/changes/<change-id>/hook-policy.system.json is missing, keep the story hook-local: surface hookRecovery.status = recovery_required with hookRecovery.reason = system_snapshot_missing instead of inventing an empty-policy fallback or lifecycle repair
• treat .da-vinci/changes/<change-id>/project-profile.system.json as a separate frozen change-local platform/locale/app-technology contract; hook or route diagnostics may reference it, but active changes must not live-read .da-vinci/project-profile.json
• treat system.project-profile.ensure as a check-only stage:start:breakdown validation seam: it may refresh .da-vinci/changes/<change-id>/project-profile.system.json only after canonical .da-vinci/project-profile.json is confirmed; profile collection remains owned by da-vinci dv-change-new [change title] / $dv-change-new before lifecycle creation
• treat .da-vinci/design-source-profile.json as the canonical project-level design-source selector; repo-owned .da-vinci/design-sources/awesome-design-md/*/DESIGN.md snapshots stay bounded advisory reference input and sibling tokens.system.json stays derived import evidence rather than route truth
• treat .da-vinci/changes/<change-id>/candidates/product-prototype.md and .da-vinci/changes/<change-id>/candidates/copy-catalog.json as generated promotion inputs; the requirement export hook may refresh them, but candidates alone never satisfy design entry
• treat .da-vinci/changes/<change-id>/requirement-truth-promotion.system.json as read-only paired-promotion evidence for accepted breakdown_to_design
• treat .da-vinci/changes/<change-id>/product-prototype.md and .da-vinci/changes/<change-id>/copy-catalog.json as promoted canonical change-local requirement-side design-entry companions; hook or route diagnostics may reference them, but only paired promotion may update them
• treat .da-vinci/changes/<change-id>/page-design-contracts.json and .da-vinci/changes/<change-id>/icon-map.json as canonical change-local design-entry contracts; hook or route diagnostics may reference them, but they are not hook-owned artifacts
• keep one canonical consumer chain for design-entry consumers: promoted product/copy truth -> page design contracts -> icon map
• when .da-vinci/design-source-profile.json is missing, treat confirmed .da-vinci/DESIGN.md as the project-local design-source baseline only when it stays rich and complete
• during breakdown, .da-vinci/DESIGN.md is read-only advisory if it already exists; do not create .da-vinci/DESIGN.md during breakdown, and leave .da-vinci/DESIGN.md missing until the design route materializes it through design-confirm --confirm
• treat .da-vinci/changes/<change-id>/source-digests.system.json as design-entry source freshness evidence; stale canonical artifacts block design entry instead of being auto-regenerated as recovery
• treat .da-vinci/changes/<change-id>/icon-supply.system.json as derived change-local icon-catalog readiness evidence; hook or route diagnostics may reference it, but it is not editable route truth
• when the shared design_to_tasks gate is rendered, keep design-entry readiness plus parallel Design Review, Icon Verification, and Copy Verification on the same fail-closed seam; WARN remains pending until explicit dv-handoff acceptance
• keep structured UI quality checks on that same seam: uiQualityScore, first-screen structured .dvp metadata, the density linter, anti-AI-look issue ids, visible text copyKey / locale, and icon iconId / qualifiedName bindings must not create a new route or workflow stage
• keep the task/build/conformance spine on existing seams: build-packet.system.json artifactSpine, derived tasks.index.json contractRefs, and implementation-conformance.system.json are replay evidence for task, build, and verify promotion, not new workflow stages or canonical source truth
• when build_to_verify replay sees missing, stale, or BLOCK implementation conformance, keep verification promotion blocked instead of treating the gap as advisory guidance
• treat .da-vinci/changes/<change-id>/quality-profile.system.json as a separate frozen change-local quality contract; hook or route diagnostics may reference it, but active changes must not live-read .da-vinci/quality-profile.json or .da-vinci/quality-profiles/*.json
• treat .da-vinci/changes/<change-id>/prd.md as a read-only derived summary owned by system stage:start:design; do not promote it to requirement truth or regenerate it from requirement handoff
• if hook-status --json is missing or invalid, keep recovery bounded to hook_status_payload_invalid or hook_status_payload_missing; hook policy mutation must wait until payload trust returns
• keep lifecycle commands explicit: da-vinci dv-change-new [change title], da-vinci dv-change-close, and da-vinci dv-change-recover <change-id> [--confirm]
• if lifecycle repair is required, do not invent a switch-change route; point the operator to $dv-repair as the maintained repair surface for abnormal lifecycle recovery

Reply contract:

• after route work, rerun da-vinci workflow-status --project <path> [--change <id>] --json and da-vinci next-step --project <path> [--change <id>] --json so the final report reflects current truth
• keep the reply in the standard Da Vinci operator format instead of a plain work log
• summarize current truth first: active change id, title, lifecycle status, derived stage, pending handoff, and blocker or repair status
• when blocked, surface Root cause: ... before any maintained next command
• include Execution detail: ... only when the underlying CLI result or gate clarifies the blocker without replacing the maintained route
• keep Evidence refs: ... high-signal on terminal-style output; richer JSON payloads may keep fuller ref lists
• preserve Failures:, Warnings:, and Notes: when present
• if exactly one legal next action exists, emit Next command: ...
• if pendingHandoff.command or the top recommended legal next command is $dv-handoff because review is still missing or WARN needs explicit acceptance, emit Next command: $dv-handoff instead of skipping directly to the downstream stage route
• if multiple legal next actions exist, group them as Recommended, Also valid, Mandatory rollback, and Rollback
• when the legal next action is another maintained Da Vinci surface, restate it using this platform's wrapper names: $dv-continue, $dv-code-context, $dv-change-new, $dv-change-close, $dv-change-recover, $dv-breakdown, $dv-handoff, $dv-design, $dv-tasks, $dv-build, $dv-verify, $dv-repair, $dv-illustration-list, $dv-illustration-prompt, $dv-illustration-add
• do not recommend raw CLI or /prompts:* actions as the next command; mention raw CLI only as execution detail inside the current maintained surface
• do not auto-invoke the next command from inside $dv-breakdown

Treat this route as the user-facing supplement requirements phase.

Before requirement editing continues:

• if da-vinci hook-bridge --project <path> [--change <id>] --trigger-kind stage:start --stage breakdown --json reports system.project-profile.ensure as BLOCK, repair or confirm .da-vinci/project-profile.json, rerun the same breakdown preflight, and only then continue requirement work
• treat .da-vinci/changes/<change-id>/project-profile.system.json as the frozen active-change platform/locale/app-technology contract during breakdown; do not live-read .da-vinci/project-profile.json after the snapshot has been refreshed
• treat the frozen appTechnology, targetPlatformTypes, and locale fields as hard requirement constraints; do not introduce a migration to another UI technology (for example Jetpack Compose) unless the active user request explicitly asks for that migration and the project profile has been intentionally updated

Before handing requirements off to design when shell access is available:

• run da-vinci lint-spec --project <path> [--change <id>] --strict
• treat command output as the gate; do not replace BLOCK or non-zero results with narrative judgment
• every .da-vinci/changes/<change-id>/specs/<capability>/spec.md must use the runtime spec contract headings with non-empty content: ## Capability, ## Behavior, ## States, ## Inputs, ## Outputs, ## Acceptance, and ## Edge Cases
• keep every spec ## Acceptance item as a one-line scenario, not a checkbox list: use - Scenario-01: When <trigger>, <observable outcome>. or - SC-AREA-1: Given <state>, when <trigger>, then <observable outcome>.
• if .da-vinci/changes/<change-id>/quality-profile.system.json declares gatePolicy.lintSpec.criticalContractFamilies, each spec must also include a non-empty section for every declared family; the default profile-critical sections are ## Actors & Entitlements, ## State Matrix, ## Failure & Recovery, ## Business Events, ## Ops & Admin Fallback, ## Billing & Limits, ## Privacy & Compliance, ## Migration & Compatibility, and ## Performance & Responsiveness
• if workflow-status / next-step keeps the route at /dv-breakdown because breakdown_to_design requirement truth, product prototype, copy catalog, or promotion evidence is stale/invalid, do not hand-edit .da-vinci/changes/<change-id>/product-prototype.md, .da-vinci/changes/<change-id>/copy-catalog.json, .da-vinci/changes/<change-id>/source-digests.system.json, or .da-vinci/changes/<change-id>/requirement-truth-promotion.system.json; run da-vinci handoff-prepare --project <path> [--change <id>] --gate breakdown_to_design --json so the system refreshes candidates and paired promotion, then rerun workflow-status / next-step
• if the primary recommended route is still $dv-breakdown, keep refining .da-vinci/changes/<change-id>/proposal.md and .da-vinci/changes/<change-id>/specs/<capability>/spec.md instead of forcing design
• once requirements are ready, stop this route and tell the user to run $dv-handoff manually; do not invoke $dv-handoff automatically from inside $dv-breakdown
• do not create target-project root-level proposal.md, specs/, design.md, tasks.md, or verification.md as part of the Da Vinci workflow

Output should move the work toward:

• .da-vinci/changes/<change-id>/proposal.md
• .da-vinci/changes/<change-id>/specs/<capability>/spec.md
• .da-vinci/changes/<change-id>/code-evidence/breakdown.json when current-code context materially informed the update

Keep .da-vinci/changes/<change-id>/proposal.md carrying exactly one consolidated handoff review section before reporting requirements ready:

• heading: ## Supplement Requirements Review
• include one bullet for each required classification: - inherited:, - new:, - changed:, - retired:, and - unresolved:
• summarize the concrete requirement deltas from the current request and prior evidence; use none only when that classification truly has no entries
• keep unresolved questions or missing evidence under - unresolved: instead of hiding them in notes
• do not tell the user to run $dv-handoff until this review section exists and da-vinci lint-spec --project <path> [--change <id>] --strict passes

Break the request into:

• scope
• pages
• flows
• states
• data needs

Use these advisory inputs when available:

• current user request plus current change requirement artifacts
• .da-vinci/code-context/index.json as project-level current-repository code context
• .da-vinci/DESIGN.md, .da-vinci/project-inventory.md, and .da-vinci/page-map.md for explicit project/platform context
• targeted live scans when .da-vinci/code-context/index.json is missing, stale, or too coarse; do not block on a missing project-level index

When current code materially affects requirement updates, write latest-only .da-vinci/changes/<change-id>/code-evidence/breakdown.json with:

• generatedAt
• sourceMode (code-context-index, targeted-live-scan, or mixed)
• projectPlatforms
• flat items carrying path, kind, summary, platforms, surfaces, and one short reason
• optional structured assumptions carrying claim, evidenceRefs, confidence, impact, needsCorrection, missingAnswer, and an optional question

Keep surfaces lightweight; they are advisory hints only and must not replace approved design surface + qualifier truth. Do not create per-run history or reverse-lookup ledgers for breakdown evidence in v1.3. Keep project-level .da-vinci/code-context/index.json advisory-only; owned brownfield assumptions belong on the active change's breakdown.json. Ask only for corrections or missing answers when current code already supports the fact pattern; do not turn supported assumptions into a reconfirmation questionnaire.