[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M786NQSD5P45AZ79P07YN2XA":3,"skill-same:01M786NQSD5P45AZ79P07YN2XA":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":14,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":33,"install":34,"resources":47},"01M786NQSD5P45AZ79P07YN2XA","sp-debug",null,"Use when a bug, regression, failed verification, or unexpected runtime behavior needs a resumable investigation and fix workflow.","chenziyang110\u002Flaunchdeck","chenziyang110","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43693913?v=4","01M7863EBWK1D0P6A29YGEMAS4","Robin11","01M7863ECM1VB6RXDMHTW90D2T",0,"MIT","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: \"sp-debug\"\ndescription: \"Use when a bug, regression, failed verification, or unexpected runtime behavior needs a resumable investigation and fix workflow.\"\ncompatibility: \"Requires spec-kit project structure with .specify\u002F directory\"\nmetadata:\n  author: \"github-spec-kit\"\n  source: \"templates\u002Fcommands\u002Fdebug.md\"\n---\n## Invocation Syntax\n\n- In this integration, invoke workflow skills with `$sp-plan`-style syntax.\n- References such as `\u002Fsp.plan`, `\u002Fsp.tasks`, or `next_command: \u002Fsp.plan` are canonical workflow-state identifiers and handoff values.\n- Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.\n\n\n\n## Workflow Contract Summary\n\n- **When to use**: A defect or failed verification needs structured root-cause investigation instead of ad hoc fixes.\n- **Primary objective**: Build a resumable debug session that gathers evidence, identifies root cause, applies a fix, and verifies the result.\n- **Primary outputs**: Debug-session state, evidence, verified fix artifacts when justified, and an honest blocked\u002Fresolved status.\n- **Default handoff**: Stay inside the debug session until resolved or blocked; route back to execution only after the defect contract is satisfied.\n- **Execution note**: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.\n\n## Blocked Exit Contract\n\nIf blocked after safe recovery, read and follow\n`.specify\u002Ftemplates\u002Fworkflow-blocker-template.md` and its JSON schema. Never\nreturn only an error or “ask a human”; preserve state and keep agent-capable\nrepair agent-owned. Set `human_action_required: true` only for authority,\ncredentials, protected systems, human decisions\u002Freviews, or physical access.\nTailor steps, expected results, failure paths, evidence, and resume action to\nCI, visual review, or product decisions. Never claim completion.\n\nFor a feature runtime blocker, do not invent `resume_argv` or overwrite an\nexisting blocker. The CLI returns a read-only `show_argv` and structured\n`resolution_action`; `next_argv` stays empty while evidence is missing. After\nthe criteria are proven, attach sanitized evidence using the action's declared\ninput and execute its base argv. It restores the same owner and keeps the full\nblocker audit.\n\n## User Input\n\n```text\n$ARGUMENTS\n```\n\nYou **MUST** consider the user input before proceeding (if not empty).\n\n## Objective\n\nDrive a resumable debugging workflow that finds the real failure mechanism before any fix is accepted.\n\n## Context\n\n- Primary inputs: the user's report, the active debug-session state, the failing runtime or verification evidence, and the task-local project cognition query bundle with readiness and returned `minimal_live_reads`.\n- The debug session file under `.planning\u002Fdebug\u002F` is the durable state source of truth for this workflow.\n- Delegated helpers are evidence collectors, not owners of the overall investigation.\n- Debug execution is complexity-based: small focused investigations may stay leader-inline, while broad or independent evidence lanes use one or more subagents.\n- Before substantive investigation, present one Debug Understanding Checkpoint covering user-owned problem facts, expected behavior, occurrence conditions, investigation boundary, explicit fix authority, assumptions to correct, and reconfirmation triggers. Technical hypotheses and the evidence sequence belong to the agent. For applicable UI symptoms, append the independent UI Confirmation target baseline and ask for one combined confirmation; record both decisions in the debug session file.\n- Treat that as the one initial full checkpoint. If later evidence materially changes the confirmed boundary or authority, use the delta-only Debug Checkpoint Amendment contract after first explaining why the prior confirmation is no longer sufficient.\n\n## Debug Checkpoint Card\n\nUse this exact Markdown table shape for the user-facing Debug Checkpoint. The\nrow labels may be localized to the reporter's language when practical, but\npreserve the canonical row meanings and the\n`| Decision to confirm | Current understanding |` structure. This table is for\nuser-owned facts and authority. Technical hypotheses belong to the agent and\nmust not be presented as decisions the user has to validate.\n\nDo not reuse the placeholder text as content. Replace every bracketed item with\nsession-specific facts. Keep the checkpoint plain text for terminal output; do\nnot use HTML tags or inline line-break markup.\n\n```markdown\n## Debug Checkpoint\n\n| Decision to confirm | Current understanding |\n| --- | --- |\n| Reported problem | [2-4 concrete sentences: the symptom or regression in user-visible terms, where it appears, why it matters, and the nearby issue this session is not debugging] |\n| Expected behavior | [what should happen instead, or the explicit unknown that the investigation must resolve] |\n| Occurrence conditions | [known environment, inputs, sequence, frequency, reproduction, failing signal, or Unknown: why it matters] |\n| Investigation boundary | Include: [behavior, workflow, state loop, environment, or affected area to investigate]. Exclude: [nearby issue, enhancement, or non-goal]. |\n| Fix authority | [Diagnose only, or diagnose and fix after evidence proves the failure mechanism; name any mutation or side-effect boundary] |\n| Assumptions to correct | [reporter assumptions or uncertain facts that should be corrected before investigation starts; use None when there are no known assumptions] |\n| Reconfirmation trigger | [the exact new defect, boundary, authority, compatibility, migration, external side effect, or material risk change that would require a new user decision] |\n```\n\nFor a visual, interaction, responsive, accessibility, TUI, or CLI presentation\nproblem, render the independent UI Confirmation card immediately after the\nDebug table. Otherwise omit it completely.\n\nThis is a conditional, independent UI confirmation card shared by Quick and\nDebug. UI applicability includes any user-visible screen, component, layout,\nnavigation or interaction flow, visual state, responsive behavior, desktop or\nmobile surface, accessibility presentation, TUI layout, or CLI presentation.\nIt does not require an external image.\n\nQuick uses this card for an implementation proposal: the user confirms the\nintended experience before implementation.\nDebug uses this card for a target baseline: the reporter confirms what the\naffected experience should be.\nThe card must not pre-approve a speculative fix or root-cause theory.\n\nRender this card only when every row can be grounded in an approved project\ndesign direction, an inspectable current product surface, or supplied source\nmaterial. `design_system.status: bootstrap` is structurally valid but is not an\napproved visual direction. For a new or high-visibility direction, first route\nto `sp-design`\u002F`spx-design` and obtain an inspectable visual artifact. For\nmulti-surface or acceptance-heavy UI, route to `sp-specify`\u002F`spx-specify`.\nDo not render an incomplete UI Confirmation as if it were approval-ready.\n\nPreserve original references rather than replacing them with prose. For each\nreference, state its reference intent, such as preserve, adapt, or inspiration.\nName the real content and image sources that will be exercised; placeholder-only\ncontent is not an adequate acceptance basis.\n\n```markdown\n## UI Confirmation\n\n| Decision to confirm | UI proposal or target baseline |\n| --- | --- |\n| Confirmation purpose | [Quick implementation proposal, or Debug target baseline; name the affected UI surface] |\n| User and primary job | [who uses this surface, the situation they are in, and the single job the experience must help them complete] |\n| Design basis and source material | [approved DESIGN.md direction, inspectable current entry point, original references with reference intent, and real content or image sources] |\n| Target experience | [visual, content, and interaction thesis plus the signature element or recognizable behavior to preserve or introduce] |\n| Structure and visible change | [information hierarchy, layout, component placement, copy, and visible before-to-after change] |\n| Interaction, states, and adaptation | [primary interaction, loading\u002Fempty\u002Ferror\u002Fsuccess\u002Fdisabled\u002Ffocus states, responsive or window adaptation, keyboard and accessibility behavior] |\n| Design boundaries | Must preserve: [non-negotiable patterns or behavior]. May adapt: [implementation-flexible details]. Must not: [visual, content, or interaction regressions]. |\n| Acceptance evidence | [real entry point, representative viewport\u002Fwindow and state matrix, structure snapshot, visual capture, runtime diagnostics, and visual comparison or explicit human review] |\n```\n\nDo not add a second reply prompt here. When this card follows a Quick or Debug\ncheckpoint, a single confirmation covers both the main checkpoint and this UI\ndecision; a correction may target only the UI rows.\n\nAfter the applicable table or tables, add a compact agent investigation summary\nfor awareness, not as a request to approve a hypothesis. It may state the first\nevidence action, fix gate, and progress signal. Those details remain agent-owned\nand must not become approval rows or a premature root-cause claim.\n\nReply with `confirm`\u002F`确认` to approve the checkpoint and, when present, the UI\ntarget baseline in one response. Reply with `revise: scope ...`\u002F`修改：范围 ...`,\n`revise: UI ...`\u002F`修改：UI ...`, or another precise correction to revise only\nthat decision.\n\n\n## Codex Project Cognition Advisory Gate\n\n**Crucial First Step**: You MUST use project cognition compass first: run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent debug '--query=\"$ARGUMENTS\"' --format json` before any investigation or fixes. Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required. Read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons, `verification_hints`, `followup_surfaces`, and `before_fix_claim`; treat `coverage_diagnostics` as confidence and closeout signals, never as route candidates. Treat `expansion_ref` as a normal continuation path and run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe expand --id '\u003Cid>' --section '\u003Csection>' --format json` only when coverage state or live evidence requires more map detail. Do not infer final edit scope from `minimal_live_reads` or `first_pass_paths`. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`. When `compass_state=needs_semantic_intake`, write `semantic_intake` from project vocabulary and rerun compass with `--semantic-intake-file`, or use the advanced `lexicon -> semantic_intake -> query` path when explicit concept decisions are needed. Preserve advanced routing through `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe query --intent debug --query-plan '\"\u003Cquery_plan_json>\"' --format json` for precision cases.\n- Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required.\n- Route every Compass packet by `recommended_next_action.action_id`, never by readiness alone. `query_ready` reads top-level `minimal_live_reads` first and then lane-level `first_pass_paths`; `review` permits only returned `minimal_live_reads` plus `coverage_diagnostics`; `needs_rebuild` may carry a resumable non-rebuild action such as `complete_scan_packets`, which must be preserved. Only `action_id=project_cognition.rebuild` may consume `rebuild_reasons[]` and the canonical Classic steps in `recommended_next_action.workflow_routes.classic.steps`; `action_id=project_cognition.repair_status` must run its returned `argv`. `blocked` reports the runtime issue as advisory map state and continues with live repository evidence unless the user's request is to repair cognition; `unsupported_runtime` continues with live evidence and records that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements instead of inferring rebuild from absent graph paths.\n- Use `map-update` for ordinary existing-baseline gaps. If `baseline_kind=greenfield_empty`, do not recommend map-scan -> map-build solely because the graph has no paths; continue with workflow artifacts and live requirements. Use `map-scan -> map-build` only for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`.\n- Treat the project cognition compass packet as advisory navigation for brownfield context; do not fall back to chat memory or ad hoc repository instincts when compass-backed runtime coverage should guide the route.\n- Treat this as advisory navigation, not a hard gate; continue with live repository evidence when the bundle is weak, stale, or missing, and use map maintenance only when it is actually useful.\n- Mutation closeout is separate from entry routing: entry stale may continue, but workflow-owned mutation closeout is not an external map-maintenance handoff. If the workflow changes source\u002Fruntime truth-owning surfaces, shared surfaces, command\u002Froute\u002Fcontract boundaries, verification entry points, runtime assumptions, or other project-related behavior surfaces, final state must run inline project cognition update from changed paths, affected surfaces, and verification evidence.\n- Inline project cognition update uses `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe delta append --help` followed by `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe update --delta-session '\"$DELTA_SESSION_ID\"' --reason workflow-finalize --format json` when a delta session exists, or `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe update --payload-file '\".specify\u002Fproject-cognition\u002Fupdates\u002F\u003Cupdate-id>.json\"' --reason workflow-finalize --format json` when no delta session exists.\n- The payload-file path must include changed_paths, behavior_surfaces, generated_surfaces, state_contracts, verification, known_unknowns, and confidence_notes so the update is equivalent to `sp-map-update`, not just a path stamp; `verification_evidence` and `generated_surface_notes` are accepted compatibility aliases.\n- Use `known_unknowns` only for blockers that make the cognition update unsafe to trust. If unrelated dirty or untracked working-tree paths were excluded by explicit workflow-owned paths, record that as `confidence_notes` or `boundary.initial_dirty_paths`, not as blocking `known_unknowns`.\n- clean closeout keys on `result_state`, not `update_id`, `last_update_id`, or freshness alone. Treat `ready` and `no_op` as clean, `partial_refresh` as recorded but not fully clean, `needs_rebuild` as a map-scan\u002Fmap-build route, `blocked` as blocked, and `recorded` as legacy recorded-only output that is never clean completion.\n- Use `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason '\"\u003Creason>\"' --format json` only when inline update cannot complete. Dirty only when inline update cannot complete.\n- `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair after user edits, interrupted workflows, or explicit operator map-maintenance requests. It is not routine cleanup for changes this workflow just made.\n- A project-cognition compass intake is not complete when it returns JSON. It is complete only when readiness drives routing, `minimal_live_reads` constrains inspection, lane-level `first_pass_paths` reasons are considered, and relevant facts are carried into the next workflow artifact or execution state.\n- Carry forward the selected capability or symptom, evidence routes, minimal reads, competing truths, and unresolved coverage gaps into debug session state before root-cause claims.\n\n## Process\n\n- Recover or initialize the debug session and current hypothesis.\n- Gather evidence through the current investigation strategy.\n- For consequence-sensitive failures, trace affected objects, dependency loops, control\u002Fobservation states, adjacent risk targets, and any `CA-###` stop-and-reopen conditions before accepting a fix.\n- Apply a fix only after the failure mechanism is understood well enough to justify it.\n- Verify the result and update the session state before any resolution claim.\n\n## Output Contract\n\n- Keep the debug session state, current hypothesis, evidence, and verification outcome explicit.\n- Produce a verified fix only when the evidence supports it.\n- Report blocked or unresolved states honestly when the investigation cannot yet close.\n\n## Guardrails\n\n- No speculative fixes before evidence supports the failure mechanism.\n- No final resolution without fresh verification evidence.\n- No subagent may take ownership of the debug session state.\n- No subagent-assisted work may continue without a safe lane; blocked debug execution records `subagent-blocked`, `execution_surface: none`, and a concrete blocked reason.\n\n## Senior Consequence Analysis Gate\n\nRun this gate whenever the request, artifact set, defect, or planned change can affect lifecycle operations, running objects, concurrent work, destructive behavior, shared state, downstream consumers, compatibility, security-sensitive behavior, or multiple plausible product behaviors.\n\nAlso trigger it for a new or changed entry point over an existing operation, a direct\u002Fbackground\u002Fheadless\u002Fsystem entry point, or a changed consumer or interaction owner. Build the result inventory from current result\u002Ferror definitions, existing consumers, state transitions, tests, and UI\u002Fwindow\u002Frequest\u002Fretry owners. Reusing an executor proves operation reuse; it does not prove that the new consumer preserves every terminal, recoverable, partial, cancelled, or user-input-required outcome.\n\nProject cognition first. Use the project cognition runtime to identify ownership, consumers, state surfaces, change-propagation facts, verification routes, conflicts, known unknowns, and coverage gaps. Senior consequence analysis second. Turn those facts into explicit product and implementation obligations instead of treating the graph as the decision-maker.\n\nProject cognition readiness provides navigation state; route recovery by `recommended_next_action.action_id`. If readiness is `query_ready`, read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons. If readiness is `review`, inspect the returned `minimal_live_reads` before continuing and treat `coverage_diagnostics` as confidence and closeout signals. If readiness is `needs_rebuild`, preserve resumable non-rebuild actions such as `complete_scan_packets`; only `action_id=project_cognition.rebuild` may consume `rebuild_reasons[]` and `recommended_next_action.workflow_routes.classic.steps` as a rebuild handoff. That rebuild route remains reserved for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`. If readiness is `blocked`, report the blocked state and continue with live repository evidence unless the user's actual request is to fix cognition runtime state. If readiness is `unsupported_runtime`, continue with live evidence and record that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements; do not recommend map-scan -> map-build solely because the graph has no paths. Carry relevant project cognition facts, returned `minimal_live_reads`, inference notes, and coverage gaps into the workflow's artifacts or durable state, but back consequence claims with live code, tests, scripts, configuration, or authoritative docs. Mutation closeout is separate from entry routing: entry stale may continue, but that does not allow source\u002Fruntime mutation workflows to defer closeout. Workflow-owned mutation closeout is not an external map-maintenance handoff; after changing project-related files or behavior, the workflow must run inline project cognition update from its changed paths, affected surfaces, and verification evidence, with `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty` only as fallback when inline update cannot complete. `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair; it is external map maintenance, not routine closeout for this workflow's own changes. In shared routing summaries, sp-map-update is for manual\u002Fexternal maintenance and ordinary existing-baseline gaps.\n\nRequired output when the gate triggers:\n\n- **Affected Object Map**: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.\n- **State-Behavior Matrix**: describe behavior for each important lifecycle state, including created, queued, running, paused, failed, cancelled, completed, resumed, archived, missing, stale, or partially refreshed states when relevant.\n- **Dependency Impact Table**: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.\n- **Recovery And Validation Contract**: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.\n- **Coverage Gaps**: list what project cognition or live evidence cannot prove, who must resolve each gap, the latest safe resolve phase, the stop-and-reopen condition, and the routing decision: current workflow may continue with an assumption, must ask the user, must route to clarification or deep research, or must request map maintenance.\n- **Consequence Obligations**: assign stable `CA-###` IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. Each `CA-###` must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition.\n- **Entrypoint Outcome Contract**: when the entry-point trigger applies, persist `entrypoint_outcome_contract` in `spec-contract.json`. Keep live-evidence-backed result inventory separate from product dispositions, and map every preserved or adapted outcome to acceptance refs and `CA-###` consequence refs. Plan and Tasks consume those CA refs through the existing consequence chain; do not create a parallel outcome ledger downstream.\n\nStand down only for docs-only wording changes, trivial isolated fixes, or local refactors that cannot affect lifecycle operations, running state, destructive operations, shared state, downstream consumers, compatibility, security, or multiple behavior choices. Record the no-trigger reason or stand-down reason in the workflow's durable artifact or closeout before skipping the required outputs.\n\nIf the gate triggers and the current workflow cannot preserve the required outputs, stop and route to the workflow that can. Do not mark ready, resolved, handoff-ready, planning-ready, or complete while triggered consequence obligations remain unresolved, unmapped, or unsupported by validation evidence.\n\n[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read `references\u002Fsemantic-work-contract.md`.\n\n## Main Flow\n\n1. Choose `leader-inline`, `subagent-assisted`, or `blocked` based on investigation size, safety, and packetizability; keep the leader responsible for session state and root-cause decisions.\n2. Create or resume the debug session, read required context, run the Debug Cognition Gate, and confirm the Debug Understanding Checkpoint before reproduction, logs, source reads, code edits, or validation.\n3. Build the causal map, investigation contract, log plan, observer framing, and first evidence path; do not form a final root cause before reproduction and evidence.\n4. Investigate one active hypothesis at a time, record eliminated alternatives, confirm root cause, and reject surface-only fixes.\n5. Apply the minimum safe fix through the selected execution model, verify with reproduction and tests, review related risks, update the debug file, and close only as resolved or blocked.\n\n## Detailed References\n\nRead [Reference index](references\u002FINDEX.md) before applying detailed contracts.\n\n- [intake and debug checkpoint](references\u002Fintake-and-debug-checkpoint.md)\n- [reproduction and evidence](references\u002Freproduction-and-evidence.md)\n- [hypothesis and root cause](references\u002Fhypothesis-and-root-cause.md)\n- [fix gate](references\u002Ffix-gate.md)\n- [regression validation and closeout](references\u002Fregression-validation-and-closeout.md)\n- [debug state](references\u002Fdebug-state.md)\n\n## Codex Leader Gate\n\nWhen running `sp-debug` in Codex, you are the **leader**, not a freeform debugger.\n\n**Crucial First Step**: You MUST use project cognition compass first: run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent debug '--query=\"$ARGUMENTS\"' --format json` before any investigation or fixes. Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required. Read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons, `verification_hints`, `followup_surfaces`, and `before_fix_claim`; treat `coverage_diagnostics` as confidence and closeout signals, never as route candidates. Treat `expansion_ref` as a normal continuation path and run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe expand --id '\u003Cid>' --section '\u003Csection>' --format json` only when coverage state or live evidence requires more map detail. Do not infer final edit scope from `minimal_live_reads` or `first_pass_paths`. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`. When `compass_state=needs_semantic_intake`, write `semantic_intake` from project vocabulary and rerun compass with `--semantic-intake-file`, or use the advanced `lexicon -> semantic_intake -> query` path when explicit concept decisions are needed. Preserve advanced routing through `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe query --intent debug --query-plan '\"\u003Cquery_plan_json>\"' --format json` for precision cases.\n\nBefore applying fixes or running investigation actions:\n- Read the current debug session state and choose `execution_model: leader-inline | subagent-assisted | blocked` from the investigation shape.\n- Use `leader-inline` for a small focused investigation with one short evidence chain.\n- Use `subagent-assisted` when there are two or more independent evidence-gathering lanes, broad surface area, or meaningful parallelism.\n- If the next step is unsafe, unavailable, or unpacketizable, record `subagent-blocked`, `execution_surface: none`, and a concrete `blocked_reason` before stopping.\n- Rejoin only at the current investigation join point, then integrate returned results on the leader path.\n\n\n## Codex Deep Debug Intake Dispatch\n\nWhen running `sp-debug` in Codex, use the project cognition compass packet as the default intake source. If the **Gathering** stage can build `map-backed-minimum-intake`, continue directly into evidence investigation with the primary candidate, contrarian candidate, transition memo, and log plan already recorded.\n\nIf project cognition is missing, ambiguous, stale, or insufficient for the failing area, Gathering may return an `await_input` containing a `think_subagent_prompt`. This prompt is a self-contained deep fallback reasoning task for a fresh subagent.\n\n**When you receive a think_subagent_prompt:**\n- Spawn a subagent with the exact prompt text via `spawn_agent`.\n- The think subagent does NOT read source code and does NOT run commands — it is a pure reasoning agent.\n- Use `wait_agent` to wait for the think subagent's result.\n- The result is hybrid: free-text analysis followed by `---` and a YAML block.\n- Parse the YAML block after `---` and populate these fields in the debug state:\n  - `causal_map` (symptom_anchor, closed_loop_path, break_edges, bypass_paths, family_coverage, candidates, adjacent_risk_targets, dimension_scan, candidate_board)\n- Ensure Stage 1A covers at least 3 families and every family includes a falsifier.\n- These Stage 1A candidates are still the observer-framing alternative cause candidates; do not collapse them into one family too early.\n- Set `causal_map_completed` to `True`.\n- Then continue the debug session — the next GatheringNode run will request the contract planner stage.\n- If Gathering returns `contract_subagent_prompt`, use it for the contract-planner subagent and feed its result back into `observer_framing`, `transition_memo`, `investigation_contract`, and top-level `log_investigation_plan`.\n- Treat the causal-map output as Stage 1A and the contract-planner output as Stage 1B. Investigation starts only after both stages are complete, unless map-backed minimum intake already completed those fields.\n- Stage 1B must still produce a primary suspected loop, a contrarian candidate, and a recommended first probe before investigation begins.\n- Do NOT skip the think subagent once the runtime requested deep fallback. Context isolation is the purpose of that step.\n\n**Hard rule:** During `investigating`, the leader must not let subagents mutate the debug file, declare the root cause final, or advance the session state.\n\n## Codex Investigation Routing Contract\n\nWhen running `sp-debug` in Codex, treat `investigating` as a complexity-based leader decision.\n- Execution model: `leader-inline | subagent-assisted | blocked`.\n- Dispatch shape: `leader-inline`, `one-subagent`, `parallel-subagents`, or `subagent-blocked`.\n- Execution surface: `leader-inline`, `native-subagents`, or `none`.\n- Subagent dispatch: Dispatch bounded subagents through `spawn_agent`.\n- Integration-native join point: Rejoin with `wait_agent`, integrate, then `close_agent`.\n- Fallback path: No managed-team or leader-inline fallback for `sp-debug`; choose `leader-inline` up front for a small focused investigation, or record `subagent-blocked` with `execution_surface: none` when the next safe step cannot proceed.\n- Small focused investigation -> `leader-inline`.\n- One safe isolated evidence lane -> `one-subagent` when the current runtime supports it safely.\n- Two or more independent evidence lanes -> `parallel-subagents` when the current runtime supports it safely.\n- Unsafe, unavailable, or unpacketizable next step -> `subagent-blocked` with `execution_surface: none` and `blocked_reason`.\n- Suitable subagent tasks include running targeted tests or repro commands, collecting logs and exit codes, searching for error text, tracing isolated code paths, and gathering evidence after diagnostic logging has been added.\n- Read `diagnostic_profile` from the debug session before choosing subagent lanes.\n- Subagents must return facts, command results, and observations; they must not update the debug file, declare the root cause final, or transition the session state.\n- Keep fixing, verification, `awaiting_human_verify`, and final session resolution on the leader path.\n\n## Codex Subagent Dispatch Contract\n\n- Execution model: `subagents-first`\n- Dispatch shape: `one-subagent`, `parallel-subagents`, or `subagent-blocked`\n- Execution surface: `native-subagents`, `managed-team`, or `leader-inline`\n- Delegation surface contract: preserve the native dispatch, fallback, worker result contract, and handoff path below.\n- Native subagent capability discovery: Before recording `subagent-blocked`, confirm the current runtime exposes `spawn_agent`, `wait_agent`, and `close_agent`; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first.\n- Do not record `subagent-blocked` until this capability discovery step is complete and the exact unavailable or unsafe surface is recorded.\n- Native subagent dispatch: Dispatch bounded subagents through `spawn_agent`.\n- Join behavior: Rejoin with `wait_agent`, integrate, then `close_agent`.\n- Managed-team fallback: No managed-team or leader-inline fallback for `sp-debug`; choose `leader-inline` up front for a small focused investigation, or record `subagent-blocked` with `execution_surface: none` when the next safe step cannot proceed.\n- Leader-inline fallback: record the reason before local execution.\n- Worker result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result handoff path: .specify\u002Fteams\u002Fstate\u002Fresults\u002F\u003Crequest-id>.json\n\n## Codex Subagent Result Contract\n\n- Worker result contract: preserve the shared `WorkerTaskResult` semantics even when the runtime calls lanes subagents.\n- Preferred result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result file handoff path: .specify\u002Fteams\u002Fstate\u002Fresults\u002F\u003Crequest-id>.json\n- Runtime-managed result paths require a dispatch request id; compute the path with `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify result path --command debug --request-id '\u003Crequest-id>'` and report final completion through the active runtime-managed result channel for that request id.\n- `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify result path --help` documents a JSON-only command; do not append `--format`.\n- Normalize subagent-reported statuses like `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, and `NEEDS_CONTEXT` into the shared `WorkerTaskResult` contract before the leader accepts the handoff.\n- Keep `reported_status` when normalization occurs so runtime-specific subagent language can be reconciled with canonical orchestration state.\n- Wait for every subagent's structured handoff before accepting the join point, closing the batch, or declaring completion.\n- Do not treat an idle subagent as done work; idle without a consumed handoff means the result channel is still unresolved.\n- Do not interrupt or shut down subagent work before the handoff has been written or explicitly reported as `BLOCKED` or `NEEDS_CONTEXT`.\n- Treat `DONE_WITH_CONCERNS` as completed work plus follow-up concerns, not as silent success.\n- Treat `NEEDS_CONTEXT` as a blocked handoff that must carry the missing context or failed assumption explicitly.\n\n## Codex Structured Question Preference\n\n- If this command was routed by `sp-auto` with `auto_default_recommendation: true`, evaluate the automatic recommended\u002Fdefault continuation gate before any question path.\n- When that gate has one safe recommended\u002Fdefault answer, you must auto-resolve the question or confirmation, record the accepted recommendation in the workflow state or summary, continue the workflow, and do not invoke the native structured question tool only to ask for that approval.\n- If the automatic gate is not safe, write the blocker and self-unblock recommendation before using the normal question path.\n- If the runtime's native structured question tool is available for the current turn and the `sp-auto` automatic gate did not resolve the question, you must use it.\n- Do not render the textual fallback block when the native tool is available.\n- Do not self-authorize textual fallback because the question seems simple, short, or easy to phrase manually.\n- Treat the template's textual question format as fallback-only guidance; use it to shape the question content, but do not render the textual block unless the native tool is unavailable in the current runtime or the tool call fails.\n- Keep native-tool availability, runtime mode, and fallback mechanics backstage. Do not tell the user that a structured question tool is unavailable, that the current runtime\u002Fmode lacks a tool, or that a fallback is being used; ask the user-facing question directly when a question is genuinely required.\n- Ask only the minimum number of questions required by this workflow's existing contract.\n- Keep the user-visible question text in the user's current language and keep option labels short.\n- Do not emit both a native tool question and the textual fallback block in the same turn. The user should see the active question exactly once.\n- If the native tool is unavailable in the current runtime or the tool call fails, ask one concise missing-information question in plain text during observer framing before entering reproduction work.\n- In `debug`, use this preference for:\n  - missing-information questions during map-backed intake\n  - deep Stage 1A\u002F1B fallback when project cognition is insufficient\n- Native tool target: `request_user_input` if the current Codex runtime exposes it\n- Question count: 1-3 short questions per call\n- Option count: 2-3 options per question\n- Required question fields: `header`, `id`, `question`, `options`\n- Option fields: `label`, `description`\n- Put the recommended option first and suffix its label with `(Recommended)` when that distinction matters.\n- Use this native surface for one bounded clarification or selection step; if it is unavailable or too narrow for the needed interaction, fall back immediately to the template's textual question format.\n\n## Codex Subagent Evidence Collection\n\nWhen running `sp-debug` in Codex, choose leader-inline or subagent-assisted evidence collection from the investigation shape.\n- Execution model: `leader-inline | subagent-assisted | blocked`.\n- Dispatch shape: `leader-inline`, `one-subagent`, `parallel-subagents`, or `subagent-blocked`.\n- Execution surface: `leader-inline`, `native-subagents`, or `none`.\n- Small focused investigation -> `leader-inline`.\n- One safe isolated evidence lane -> `one-subagent` when the current runtime supports it safely.\n- Two or more independent evidence lanes -> `parallel-subagents` when the current runtime supports it safely.\n- Unsafe, unavailable, or unpacketizable next step -> `subagent-blocked` with `execution_surface: none` and `blocked_reason`.\n- If there are two or more independent evidence-gathering lanes, dispatch subagents through `spawn_agent` instead of doing manual sequential investigation.\n- Suitable subagent tasks include running targeted tests or repro commands, collecting logs and exit codes, searching for error text, tracing isolated code paths, and gathering evidence after diagnostic logging has been added.\n- Read `diagnostic_profile` from the debug session before choosing subagent lanes.\n- The leader **MUST** update the debug file's `Current Focus` before dispatching subagents and treat subagent work as evidence collection for the current hypothesis.\n- The think-subagent output is an investigation contract, not advisory prose.\n- The investigating stage must consume the candidate queue and primary candidate before freeform fixes begin.\n- After two automated verification failures, switch the session into root-cause mode and stop layering point fixes.\n- Do not close the session until nearest-neighbor related risk targets have been reviewed.\n- Subagents must return facts, command results, and observations; they must not update the debug file, declare the root cause final, or transition the session state.\n- Wait for every subagent's structured handoff before accepting the join point or changing the investigation stage.\n- Wait for every delegated lane's structured handoff before accepting the join point or changing the investigation stage.\n- Do not treat an idle subagent as done work; idle without a consumed handoff means the evidence lane is still unresolved.\n- Do not interrupt or shut down subagent work before the handoff has been written or explicitly reported as `BLOCKED` or `NEEDS_CONTEXT`.\n- Use `wait_agent` only after the current investigation fan-out reaches its join point.\n- Use `close_agent` after integrating finished subagent results.\n- Do not resolve the session directly from successful automated verification. Successful automated verification must hand off into formal human verification.\n- If human feedback reports another problem, classify it as `same_issue`, `derived_issue`, or `unrelated_issue`.\n- Default to `same_issue` unless strong evidence proves the other classes.\n- Keep fixing, agent verification, `awaiting_human_verify`, and final session resolution on the leader path.\n","## Invocation Syntax\n\n- In this integration, invoke workflow skills with `$sp-plan`-style syntax.\n- References such as `\u002Fsp.plan`, `\u002Fsp.tasks`, or `next_command: \u002Fsp.plan` are canonical workflow-state identifiers and handoff values.\n- Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.\n\n\n\n## Workflow Contract Summary\n\n- **When to use**: A defect or failed verification needs structured root-cause investigation instead of ad hoc fixes.\n- **Primary objective**: Build a resumable debug session that gathers evidence, identifies root cause, applies a fix, and verifies the result.\n- **Primary outputs**: Debug-session state, evidence, verified fix artifacts when justified, and an honest blocked\u002Fresolved status.\n- **Default handoff**: Stay inside the debug session until resolved or blocked; route back to execution only after the defect contract is satisfied.\n- **Execution note**: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.\n\n## Blocked Exit Contract\n\nIf blocked after safe recovery, read and follow\n`.specify\u002Ftemplates\u002Fworkflow-blocker-template.md` and its JSON schema. Never\nreturn only an error or “ask a human”; preserve state and keep agent-capable\nrepair agent-owned. Set `human_action_required: true` only for authority,\ncredentials, protected systems, human decisions\u002Freviews, or physical access.\nTailor steps, expected results, failure paths, evidence, and resume action to\nCI, visual review, or product decisions. Never claim completion.\n\nFor a feature runtime blocker, do not invent `resume_argv` or overwrite an\nexisting blocker. The CLI returns a read-only `show_argv` and structured\n`resolution_action`; `next_argv` stays empty while evidence is missing. After\nthe criteria are proven, attach sanitized evidence using the action's declared\ninput and execute its base argv. It restores the same owner and keeps the full\nblocker audit.\n\n## User Input\n\n```text\n$ARGUMENTS\n```\n\nYou **MUST** consider the user input before proceeding (if not empty).\n\n## Objective\n\nDrive a resumable debugging workflow that finds the real failure mechanism before any fix is accepted.\n\n## Context\n\n- Primary inputs: the user's report, the active debug-session state, the failing runtime or verification evidence, and the task-local project cognition query bundle with readiness and returned `minimal_live_reads`.\n- The debug session file under `.planning\u002Fdebug\u002F` is the durable state source of truth for this workflow.\n- Delegated helpers are evidence collectors, not owners of the overall investigation.\n- Debug execution is complexity-based: small focused investigations may stay leader-inline, while broad or independent evidence lanes use one or more subagents.\n- Before substantive investigation, present one Debug Understanding Checkpoint covering user-owned problem facts, expected behavior, occurrence conditions, investigation boundary, explicit fix authority, assumptions to correct, and reconfirmation triggers. Technical hypotheses and the evidence sequence belong to the agent. For applicable UI symptoms, append the independent UI Confirmation target baseline and ask for one combined confirmation; record both decisions in the debug session file.\n- Treat that as the one initial full checkpoint. If later evidence materially changes the confirmed boundary or authority, use the delta-only Debug Checkpoint Amendment contract after first explaining why the prior confirmation is no longer sufficient.\n\n## Debug Checkpoint Card\n\nUse this exact Markdown table shape for the user-facing Debug Checkpoint. The\nrow labels may be localized to the reporter's language when practical, but\npreserve the canonical row meanings and the\n`| Decision to confirm | Current understanding |` structure. This table is for\nuser-owned facts and authority. Technical hypotheses belong to the agent and\nmust not be presented as decisions the user has to validate.\n\nDo not reuse the placeholder text as content. Replace every bracketed item with\nsession-specific facts. Keep the checkpoint plain text for terminal output; do\nnot use HTML tags or inline line-break markup.\n\n```markdown\n## Debug Checkpoint\n\n| Decision to confirm | Current understanding |\n| --- | --- |\n| Reported problem | [2-4 concrete sentences: the symptom or regression in user-visible terms, where it appears, why it matters, and the nearby issue this session is not debugging] |\n| Expected behavior | [what should happen instead, or the explicit unknown that the investigation must resolve] |\n| Occurrence conditions | [known environment, inputs, sequence, frequency, reproduction, failing signal, or Unknown: why it matters] |\n| Investigation boundary | Include: [behavior, workflow, state loop, environment, or affected area to investigate]. Exclude: [nearby issue, enhancement, or non-goal]. |\n| Fix authority | [Diagnose only, or diagnose and fix after evidence proves the failure mechanism; name any mutation or side-effect boundary] |\n| Assumptions to correct | [reporter assumptions or uncertain facts that should be corrected before investigation starts; use None when there are no known assumptions] |\n| Reconfirmation trigger | [the exact new defect, boundary, authority, compatibility, migration, external side effect, or material risk change that would require a new user decision] |\n```\n\nFor a visual, interaction, responsive, accessibility, TUI, or CLI presentation\nproblem, render the independent UI Confirmation card immediately after the\nDebug table. Otherwise omit it completely.\n\nThis is a conditional, independent UI confirmation card shared by Quick and\nDebug. UI applicability includes any user-visible screen, component, layout,\nnavigation or interaction flow, visual state, responsive behavior, desktop or\nmobile surface, accessibility presentation, TUI layout, or CLI presentation.\nIt does not require an external image.\n\nQuick uses this card for an implementation proposal: the user confirms the\nintended experience before implementation.\nDebug uses this card for a target baseline: the reporter confirms what the\naffected experience should be.\nThe card must not pre-approve a speculative fix or root-cause theory.\n\nRender this card only when every row can be grounded in an approved project\ndesign direction, an inspectable current product surface, or supplied source\nmaterial. `design_system.status: bootstrap` is structurally valid but is not an\napproved visual direction. For a new or high-visibility direction, first route\nto `sp-design`\u002F`spx-design` and obtain an inspectable visual artifact. For\nmulti-surface or acceptance-heavy UI, route to `sp-specify`\u002F`spx-specify`.\nDo not render an incomplete UI Confirmation as if it were approval-ready.\n\nPreserve original references rather than replacing them with prose. For each\nreference, state its reference intent, such as preserve, adapt, or inspiration.\nName the real content and image sources that will be exercised; placeholder-only\ncontent is not an adequate acceptance basis.\n\n```markdown\n## UI Confirmation\n\n| Decision to confirm | UI proposal or target baseline |\n| --- | --- |\n| Confirmation purpose | [Quick implementation proposal, or Debug target baseline; name the affected UI surface] |\n| User and primary job | [who uses this surface, the situation they are in, and the single job the experience must help them complete] |\n| Design basis and source material | [approved DESIGN.md direction, inspectable current entry point, original references with reference intent, and real content or image sources] |\n| Target experience | [visual, content, and interaction thesis plus the signature element or recognizable behavior to preserve or introduce] |\n| Structure and visible change | [information hierarchy, layout, component placement, copy, and visible before-to-after change] |\n| Interaction, states, and adaptation | [primary interaction, loading\u002Fempty\u002Ferror\u002Fsuccess\u002Fdisabled\u002Ffocus states, responsive or window adaptation, keyboard and accessibility behavior] |\n| Design boundaries | Must preserve: [non-negotiable patterns or behavior]. May adapt: [implementation-flexible details]. Must not: [visual, content, or interaction regressions]. |\n| Acceptance evidence | [real entry point, representative viewport\u002Fwindow and state matrix, structure snapshot, visual capture, runtime diagnostics, and visual comparison or explicit human review] |\n```\n\nDo not add a second reply prompt here. When this card follows a Quick or Debug\ncheckpoint, a single confirmation covers both the main checkpoint and this UI\ndecision; a correction may target only the UI rows.\n\nAfter the applicable table or tables, add a compact agent investigation summary\nfor awareness, not as a request to approve a hypothesis. It may state the first\nevidence action, fix gate, and progress signal. Those details remain agent-owned\nand must not become approval rows or a premature root-cause claim.\n\nReply with `confirm`\u002F`确认` to approve the checkpoint and, when present, the UI\ntarget baseline in one response. Reply with `revise: scope ...`\u002F`修改：范围 ...`,\n`revise: UI ...`\u002F`修改：UI ...`, or another precise correction to revise only\nthat decision.\n\n\n## Codex Project Cognition Advisory Gate\n\n**Crucial First Step**: You MUST use project cognition compass first: run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent debug '--query=\"$ARGUMENTS\"' --format json` before any investigation or fixes. Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required. Read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons, `verification_hints`, `followup_surfaces`, and `before_fix_claim`; treat `coverage_diagnostics` as confidence and closeout signals, never as route candidates. Treat `expansion_ref` as a normal continuation path and run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe expand --id '\u003Cid>' --section '\u003Csection>' --format json` only when coverage state or live evidence requires more map detail. Do not infer final edit scope from `minimal_live_reads` or `first_pass_paths`. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`. When `compass_state=needs_semantic_intake`, write `semantic_intake` from project vocabulary and rerun compass with `--semantic-intake-file`, or use the advanced `lexicon -> semantic_intake -> query` path when explicit concept decisions are needed. Preserve advanced routing through `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe query --intent debug --query-plan '\"\u003Cquery_plan_json>\"' --format json` for precision cases.\n- Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required.\n- Route every Compass packet by `recommended_next_action.action_id`, never by readiness alone. `query_ready` reads top-level `minimal_live_reads` first and then lane-level `first_pass_paths`; `review` permits only returned `minimal_live_reads` plus `coverage_diagnostics`; `needs_rebuild` may carry a resumable non-rebuild action such as `complete_scan_packets`, which must be preserved. Only `action_id=project_cognition.rebuild` may consume `rebuild_reasons[]` and the canonical Classic steps in `recommended_next_action.workflow_routes.classic.steps`; `action_id=project_cognition.repair_status` must run its returned `argv`. `blocked` reports the runtime issue as advisory map state and continues with live repository evidence unless the user's request is to repair cognition; `unsupported_runtime` continues with live evidence and records that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements instead of inferring rebuild from absent graph paths.\n- Use `map-update` for ordinary existing-baseline gaps. If `baseline_kind=greenfield_empty`, do not recommend map-scan -> map-build solely because the graph has no paths; continue with workflow artifacts and live requirements. Use `map-scan -> map-build` only for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`.\n- Treat the project cognition compass packet as advisory navigation for brownfield context; do not fall back to chat memory or ad hoc repository instincts when compass-backed runtime coverage should guide the route.\n- Treat this as advisory navigation, not a hard gate; continue with live repository evidence when the bundle is weak, stale, or missing, and use map maintenance only when it is actually useful.\n- Mutation closeout is separate from entry routing: entry stale may continue, but workflow-owned mutation closeout is not an external map-maintenance handoff. If the workflow changes source\u002Fruntime truth-owning surfaces, shared surfaces, command\u002Froute\u002Fcontract boundaries, verification entry points, runtime assumptions, or other project-related behavior surfaces, final state must run inline project cognition update from changed paths, affected surfaces, and verification evidence.\n- Inline project cognition update uses `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe delta append --help` followed by `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe update --delta-session '\"$DELTA_SESSION_ID\"' --reason workflow-finalize --format json` when a delta session exists, or `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe update --payload-file '\".specify\u002Fproject-cognition\u002Fupdates\u002F\u003Cupdate-id>.json\"' --reason workflow-finalize --format json` when no delta session exists.\n- The payload-file path must include changed_paths, behavior_surfaces, generated_surfaces, state_contracts, verification, known_unknowns, and confidence_notes so the update is equivalent to `sp-map-update`, not just a path stamp; `verification_evidence` and `generated_surface_notes` are accepted compatibility aliases.\n- Use `known_unknowns` only for blockers that make the cognition update unsafe to trust. If unrelated dirty or untracked working-tree paths were excluded by explicit workflow-owned paths, record that as `confidence_notes` or `boundary.initial_dirty_paths`, not as blocking `known_unknowns`.\n- clean closeout keys on `result_state`, not `update_id`, `last_update_id`, or freshness alone. Treat `ready` and `no_op` as clean, `partial_refresh` as recorded but not fully clean, `needs_rebuild` as a map-scan\u002Fmap-build route, `blocked` as blocked, and `recorded` as legacy recorded-only output that is never clean completion.\n- Use `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty --reason '\"\u003Creason>\"' --format json` only when inline update cannot complete. Dirty only when inline update cannot complete.\n- `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair after user edits, interrupted workflows, or explicit operator map-maintenance requests. It is not routine cleanup for changes this workflow just made.\n- A project-cognition compass intake is not complete when it returns JSON. It is complete only when readiness drives routing, `minimal_live_reads` constrains inspection, lane-level `first_pass_paths` reasons are considered, and relevant facts are carried into the next workflow artifact or execution state.\n- Carry forward the selected capability or symptom, evidence routes, minimal reads, competing truths, and unresolved coverage gaps into debug session state before root-cause claims.\n\n## Process\n\n- Recover or initialize the debug session and current hypothesis.\n- Gather evidence through the current investigation strategy.\n- For consequence-sensitive failures, trace affected objects, dependency loops, control\u002Fobservation states, adjacent risk targets, and any `CA-###` stop-and-reopen conditions before accepting a fix.\n- Apply a fix only after the failure mechanism is understood well enough to justify it.\n- Verify the result and update the session state before any resolution claim.\n\n## Output Contract\n\n- Keep the debug session state, current hypothesis, evidence, and verification outcome explicit.\n- Produce a verified fix only when the evidence supports it.\n- Report blocked or unresolved states honestly when the investigation cannot yet close.\n\n## Guardrails\n\n- No speculative fixes before evidence supports the failure mechanism.\n- No final resolution without fresh verification evidence.\n- No subagent may take ownership of the debug session state.\n- No subagent-assisted work may continue without a safe lane; blocked debug execution records `subagent-blocked`, `execution_surface: none`, and a concrete blocked reason.\n\n## Senior Consequence Analysis Gate\n\nRun this gate whenever the request, artifact set, defect, or planned change can affect lifecycle operations, running objects, concurrent work, destructive behavior, shared state, downstream consumers, compatibility, security-sensitive behavior, or multiple plausible product behaviors.\n\nAlso trigger it for a new or changed entry point over an existing operation, a direct\u002Fbackground\u002Fheadless\u002Fsystem entry point, or a changed consumer or interaction owner. Build the result inventory from current result\u002Ferror definitions, existing consumers, state transitions, tests, and UI\u002Fwindow\u002Frequest\u002Fretry owners. Reusing an executor proves operation reuse; it does not prove that the new consumer preserves every terminal, recoverable, partial, cancelled, or user-input-required outcome.\n\nProject cognition first. Use the project cognition runtime to identify ownership, consumers, state surfaces, change-propagation facts, verification routes, conflicts, known unknowns, and coverage gaps. Senior consequence analysis second. Turn those facts into explicit product and implementation obligations instead of treating the graph as the decision-maker.\n\nProject cognition readiness provides navigation state; route recovery by `recommended_next_action.action_id`. If readiness is `query_ready`, read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons. If readiness is `review`, inspect the returned `minimal_live_reads` before continuing and treat `coverage_diagnostics` as confidence and closeout signals. If readiness is `needs_rebuild`, preserve resumable non-rebuild actions such as `complete_scan_packets`; only `action_id=project_cognition.rebuild` may consume `rebuild_reasons[]` and `recommended_next_action.workflow_routes.classic.steps` as a rebuild handoff. That rebuild route remains reserved for brownfield first\u002Fmissing\u002Funusable baseline, schema failure, schema v1 or old broad-schema rebuild-required readiness, zero active-generation `path_index` rows outside `greenfield_empty`, missing or invalid `alias_index`, `explicit_rebuild_requested`, or `baseline_identity_invalid`. If readiness is `blocked`, report the blocked state and continue with live repository evidence unless the user's actual request is to fix cognition runtime state. If readiness is `unsupported_runtime`, continue with live evidence and record that compass intake was unavailable. If `baseline_kind=greenfield_empty`, continue with workflow artifacts and live requirements; do not recommend map-scan -> map-build solely because the graph has no paths. Carry relevant project cognition facts, returned `minimal_live_reads`, inference notes, and coverage gaps into the workflow's artifacts or durable state, but back consequence claims with live code, tests, scripts, configuration, or authoritative docs. Mutation closeout is separate from entry routing: entry stale may continue, but that does not allow source\u002Fruntime mutation workflows to defer closeout. Workflow-owned mutation closeout is not an external map-maintenance handoff; after changing project-related files or behavior, the workflow must run inline project cognition update from its changed paths, affected surfaces, and verification evidence, with `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe mark-dirty` only as fallback when inline update cannot complete. `sp-map-update` is for manual\u002Fexternal maintenance and follow-up repair; it is external map maintenance, not routine closeout for this workflow's own changes. In shared routing summaries, sp-map-update is for manual\u002Fexternal maintenance and ordinary existing-baseline gaps.\n\nRequired output when the gate triggers:\n\n- **Affected Object Map**: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.\n- **State-Behavior Matrix**: describe behavior for each important lifecycle state, including created, queued, running, paused, failed, cancelled, completed, resumed, archived, missing, stale, or partially refreshed states when relevant.\n- **Dependency Impact Table**: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.\n- **Recovery And Validation Contract**: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.\n- **Coverage Gaps**: list what project cognition or live evidence cannot prove, who must resolve each gap, the latest safe resolve phase, the stop-and-reopen condition, and the routing decision: current workflow may continue with an assumption, must ask the user, must route to clarification or deep research, or must request map maintenance.\n- **Consequence Obligations**: assign stable `CA-###` IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. Each `CA-###` must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition.\n- **Entrypoint Outcome Contract**: when the entry-point trigger applies, persist `entrypoint_outcome_contract` in `spec-contract.json`. Keep live-evidence-backed result inventory separate from product dispositions, and map every preserved or adapted outcome to acceptance refs and `CA-###` consequence refs. Plan and Tasks consume those CA refs through the existing consequence chain; do not create a parallel outcome ledger downstream.\n\nStand down only for docs-only wording changes, trivial isolated fixes, or local refactors that cannot affect lifecycle operations, running state, destructive operations, shared state, downstream consumers, compatibility, security, or multiple behavior choices. Record the no-trigger reason or stand-down reason in the workflow's durable artifact or closeout before skipping the required outputs.\n\nIf the gate triggers and the current workflow cannot preserve the required outputs, stop and route to the workflow that can. Do not mark ready, resolved, handoff-ready, planning-ready, or complete while triggered consequence obligations remain unresolved, unmapped, or unsupported by validation evidence.\n\n[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read `references\u002Fsemantic-work-contract.md`.\n\n## Main Flow\n\n1. Choose `leader-inline`, `subagent-assisted`, or `blocked` based on investigation size, safety, and packetizability; keep the leader responsible for session state and root-cause decisions.\n2. Create or resume the debug session, read required context, run the Debug Cognition Gate, and confirm the Debug Understanding Checkpoint before reproduction, logs, source reads, code edits, or validation.\n3. Build the causal map, investigation contract, log plan, observer framing, and first evidence path; do not form a final root cause before reproduction and evidence.\n4. Investigate one active hypothesis at a time, record eliminated alternatives, confirm root cause, and reject surface-only fixes.\n5. Apply the minimum safe fix through the selected execution model, verify with reproduction and tests, review related risks, update the debug file, and close only as resolved or blocked.\n\n## Detailed References\n\nRead [Reference index](references\u002FINDEX.md) before applying detailed contracts.\n\n- [intake and debug checkpoint](references\u002Fintake-and-debug-checkpoint.md)\n- [reproduction and evidence](references\u002Freproduction-and-evidence.md)\n- [hypothesis and root cause](references\u002Fhypothesis-and-root-cause.md)\n- [fix gate](references\u002Ffix-gate.md)\n- [regression validation and closeout](references\u002Fregression-validation-and-closeout.md)\n- [debug state](references\u002Fdebug-state.md)\n\n## Codex Leader Gate\n\nWhen running `sp-debug` in Codex, you are the **leader**, not a freeform debugger.\n\n**Crucial First Step**: You MUST use project cognition compass first: run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe compass --intent debug '--query=\"$ARGUMENTS\"' --format json` before any investigation or fixes. Read and carry `epistemic_contract`; require `graph_role=route_candidate_only`, `fact_source_of_truth=live_repository`, `live_verification_required=true`, `graph_only_claims_allowed=false`, and `unverified_claim_action=withhold`. The contract cannot authorize source changes and cannot prove current behavior; contradictory live evidence overrides the route candidate. Graph claims are indexed assertions; even `verified_in_graph_generation` is only an active graph-generation state, not current repository truth. Graph claims cannot authorize source changes and cannot set workflow `claim_ready=true`; bounded live evidence and the separate workflow final-claim gate remain required. Read top-level `minimal_live_reads` first, then use lane-level `first_pass_paths` reasons, `verification_hints`, `followup_surfaces`, and `before_fix_claim`; treat `coverage_diagnostics` as confidence and closeout signals, never as route candidates. Treat `expansion_ref` as a normal continuation path and run `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe expand --id '\u003Cid>' --section '\u003Csection>' --format json` only when coverage state or live evidence requires more map detail. Do not infer final edit scope from `minimal_live_reads` or `first_pass_paths`. Readiness values are `query_ready`, `review`, `needs_rebuild`, `blocked`, and `unsupported_runtime`. When `compass_state=needs_semantic_intake`, write `semantic_intake` from project vocabulary and rerun compass with `--semantic-intake-file`, or use the advanced `lexicon -> semantic_intake -> query` path when explicit concept decisions are needed. Preserve advanced routing through `C:\\Users\\11034\\.specify\\bin\\project-cognition.exe query --intent debug --query-plan '\"\u003Cquery_plan_json>\"' --format json` for precision cases.\n\nBefore applying fixes or running investigation actions:\n- Read the current debug session state and choose `execution_model: leader-inline | subagent-assisted | blocked` from the investigation shape.\n- Use `leader-inline` for a small focused investigation with one short evidence chain.\n- Use `subagent-assisted` when there are two or more independent evidence-gathering lanes, broad surface area, or meaningful parallelism.\n- If the next step is unsafe, unavailable, or unpacketizable, record `subagent-blocked`, `execution_surface: none`, and a concrete `blocked_reason` before stopping.\n- Rejoin only at the current investigation join point, then integrate returned results on the leader path.\n\n\n## Codex Deep Debug Intake Dispatch\n\nWhen running `sp-debug` in Codex, use the project cognition compass packet as the default intake source. If the **Gathering** stage can build `map-backed-minimum-intake`, continue directly into evidence investigation with the primary candidate, contrarian candidate, transition memo, and log plan already recorded.\n\nIf project cognition is missing, ambiguous, stale, or insufficient for the failing area, Gathering may return an `await_input` containing a `think_subagent_prompt`. This prompt is a self-contained deep fallback reasoning task for a fresh subagent.\n\n**When you receive a think_subagent_prompt:**\n- Spawn a subagent with the exact prompt text via `spawn_agent`.\n- The think subagent does NOT read source code and does NOT run commands — it is a pure reasoning agent.\n- Use `wait_agent` to wait for the think subagent's result.\n- The result is hybrid: free-text analysis followed by `---` and a YAML block.\n- Parse the YAML block after `---` and populate these fields in the debug state:\n  - `causal_map` (symptom_anchor, closed_loop_path, break_edges, bypass_paths, family_coverage, candidates, adjacent_risk_targets, dimension_scan, candidate_board)\n- Ensure Stage 1A covers at least 3 families and every family includes a falsifier.\n- These Stage 1A candidates are still the observer-framing alternative cause candidates; do not collapse them into one family too early.\n- Set `causal_map_completed` to `True`.\n- Then continue the debug session — the next GatheringNode run will request the contract planner stage.\n- If Gathering returns `contract_subagent_prompt`, use it for the contract-planner subagent and feed its result back into `observer_framing`, `transition_memo`, `investigation_contract`, and top-level `log_investigation_plan`.\n- Treat the causal-map output as Stage 1A and the contract-planner output as Stage 1B. Investigation starts only after both stages are complete, unless map-backed minimum intake already completed those fields.\n- Stage 1B must still produce a primary suspected loop, a contrarian candidate, and a recommended first probe before investigation begins.\n- Do NOT skip the think subagent once the runtime requested deep fallback. Context isolation is the purpose of that step.\n\n**Hard rule:** During `investigating`, the leader must not let subagents mutate the debug file, declare the root cause final, or advance the session state.\n\n## Codex Investigation Routing Contract\n\nWhen running `sp-debug` in Codex, treat `investigating` as a complexity-based leader decision.\n- Execution model: `leader-inline | subagent-assisted | blocked`.\n- Dispatch shape: `leader-inline`, `one-subagent`, `parallel-subagents`, or `subagent-blocked`.\n- Execution surface: `leader-inline`, `native-subagents`, or `none`.\n- Subagent dispatch: Dispatch bounded subagents through `spawn_agent`.\n- Integration-native join point: Rejoin with `wait_agent`, integrate, then `close_agent`.\n- Fallback path: No managed-team or leader-inline fallback for `sp-debug`; choose `leader-inline` up front for a small focused investigation, or record `subagent-blocked` with `execution_surface: none` when the next safe step cannot proceed.\n- Small focused investigation -> `leader-inline`.\n- One safe isolated evidence lane -> `one-subagent` when the current runtime supports it safely.\n- Two or more independent evidence lanes -> `parallel-subagents` when the current runtime supports it safely.\n- Unsafe, unavailable, or unpacketizable next step -> `subagent-blocked` with `execution_surface: none` and `blocked_reason`.\n- Suitable subagent tasks include running targeted tests or repro commands, collecting logs and exit codes, searching for error text, tracing isolated code paths, and gathering evidence after diagnostic logging has been added.\n- Read `diagnostic_profile` from the debug session before choosing subagent lanes.\n- Subagents must return facts, command results, and observations; they must not update the debug file, declare the root cause final, or transition the session state.\n- Keep fixing, verification, `awaiting_human_verify`, and final session resolution on the leader path.\n\n## Codex Subagent Dispatch Contract\n\n- Execution model: `subagents-first`\n- Dispatch shape: `one-subagent`, `parallel-subagents`, or `subagent-blocked`\n- Execution surface: `native-subagents`, `managed-team`, or `leader-inline`\n- Delegation surface contract: preserve the native dispatch, fallback, worker result contract, and handoff path below.\n- Native subagent capability discovery: Before recording `subagent-blocked`, confirm the current runtime exposes `spawn_agent`, `wait_agent`, and `close_agent`; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first.\n- Do not record `subagent-blocked` until this capability discovery step is complete and the exact unavailable or unsafe surface is recorded.\n- Native subagent dispatch: Dispatch bounded subagents through `spawn_agent`.\n- Join behavior: Rejoin with `wait_agent`, integrate, then `close_agent`.\n- Managed-team fallback: No managed-team or leader-inline fallback for `sp-debug`; choose `leader-inline` up front for a small focused investigation, or record `subagent-blocked` with `execution_surface: none` when the next safe step cannot proceed.\n- Leader-inline fallback: record the reason before local execution.\n- Worker result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result handoff path: .specify\u002Fteams\u002Fstate\u002Fresults\u002F\u003Crequest-id>.json\n\n## Codex Subagent Result Contract\n\n- Worker result contract: preserve the shared `WorkerTaskResult` semantics even when the runtime calls lanes subagents.\n- Preferred result contract: Fact-only evidence payload: hypothesis tested, commands run, files inspected, observations, confidence, blocker.\n- Result file handoff path: .specify\u002Fteams\u002Fstate\u002Fresults\u002F\u003Crequest-id>.json\n- Runtime-managed result paths require a dispatch request id; compute the path with `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify result path --command debug --request-id '\u003Crequest-id>'` and report final completion through the active runtime-managed result channel for that request id.\n- `uvx --from git+https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Fspec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify result path --help` documents a JSON-only command; do not append `--format`.\n- Normalize subagent-reported statuses like `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, and `NEEDS_CONTEXT` into the shared `WorkerTaskResult` contract before the leader accepts the handoff.\n- Keep `reported_status` when normalization occurs so runtime-specific subagent language can be reconciled with canonical orchestration state.\n- Wait for every subagent's structured handoff before accepting the join point, closing the batch, or declaring completion.\n- Do not treat an idle subagent as done work; idle without a consumed handoff means the result channel is still unresolved.\n- Do not interrupt or shut down subagent work before the handoff has been written or explicitly reported as `BLOCKED` or `NEEDS_CONTEXT`.\n- Treat `DONE_WITH_CONCERNS` as completed work plus follow-up concerns, not as silent success.\n- Treat `NEEDS_CONTEXT` as a blocked handoff that must carry the missing context or failed assumption explicitly.\n\n## Codex Structured Question Preference\n\n- If this command was routed by `sp-auto` with `auto_default_recommendation: true`, evaluate the automatic recommended\u002Fdefault continuation gate before any question path.\n- When that gate has one safe recommended\u002Fdefault answer, you must auto-resolve the question or confirmation, record the accepted recommendation in the workflow state or summary, continue the workflow, and do not invoke the native structured question tool only to ask for that approval.\n- If the automatic gate is not safe, write the blocker and self-unblock recommendation before using the normal question path.\n- If the runtime's native structured question tool is available for the current turn and the `sp-auto` automatic gate did not resolve the question, you must use it.\n- Do not render the textual fallback block when the native tool is available.\n- Do not self-authorize textual fallback because the question seems simple, short, or easy to phrase manually.\n- Treat the template's textual question format as fallback-only guidance; use it to shape the question content, but do not render the textual block unless the native tool is unavailable in the current runtime or the tool call fails.\n- Keep native-tool availability, runtime mode, and fallback mechanics backstage. Do not tell the user that a structured question tool is unavailable, that the current runtime\u002Fmode lacks a tool, or that a fallback is being used; ask the user-facing question directly when a question is genuinely required.\n- Ask only the minimum number of questions required by this workflow's existing contract.\n- Keep the user-visible question text in the user's current language and keep option labels short.\n- Do not emit both a native tool question and the textual fallback block in the same turn. The user should see the active question exactly once.\n- If the native tool is unavailable in the current runtime or the tool call fails, ask one concise missing-information question in plain text during observer framing before entering reproduction work.\n- In `debug`, use this preference for:\n  - missing-information questions during map-backed intake\n  - deep Stage 1A\u002F1B fallback when project cognition is insufficient\n- Native tool target: `request_user_input` if the current Codex runtime exposes it\n- Question count: 1-3 short questions per call\n- Option count: 2-3 options per question\n- Required question fields: `header`, `id`, `question`, `options`\n- Option fields: `label`, `description`\n- Put the recommended option first and suffix its label with `(Recommended)` when that distinction matters.\n- Use this native surface for one bounded clarification or selection step; if it is unavailable or too narrow for the needed interaction, fall back immediately to the template's textual question format.\n\n## Codex Subagent Evidence Collection\n\nWhen running `sp-debug` in Codex, choose leader-inline or subagent-assisted evidence collection from the investigation shape.\n- Execution model: `leader-inline | subagent-assisted | blocked`.\n- Dispatch shape: `leader-inline`, `one-subagent`, `parallel-subagents`, or `subagent-blocked`.\n- Execution surface: `leader-inline`, `native-subagents`, or `none`.\n- Small focused investigation -> `leader-inline`.\n- One safe isolated evidence lane -> `one-subagent` when the current runtime supports it safely.\n- Two or more independent evidence lanes -> `parallel-subagents` when the current runtime supports it safely.\n- Unsafe, unavailable, or unpacketizable next step -> `subagent-blocked` with `execution_surface: none` and `blocked_reason`.\n- If there are two or more independent evidence-gathering lanes, dispatch subagents through `spawn_agent` instead of doing manual sequential investigation.\n- Suitable subagent tasks include running targeted tests or repro commands, collecting logs and exit codes, searching for error text, tracing isolated code paths, and gathering evidence after diagnostic logging has been added.\n- Read `diagnostic_profile` from the debug session before choosing subagent lanes.\n- The leader **MUST** update the debug file's `Current Focus` before dispatching subagents and treat subagent work as evidence collection for the current hypothesis.\n- The think-subagent output is an investigation contract, not advisory prose.\n- The investigating stage must consume the candidate queue and primary candidate before freeform fixes begin.\n- After two automated verification failures, switch the session into root-cause mode and stop layering point fixes.\n- Do not close the session until nearest-neighbor related risk targets have been reviewed.\n- Subagents must return facts, command results, and observations; they must not update the debug file, declare the root cause final, or transition the session state.\n- Wait for every subagent's structured handoff before accepting the join point or changing the investigation stage.\n- Wait for every delegated lane's structured handoff before accepting the join point or changing the investigation stage.\n- Do not treat an idle subagent as done work; idle without a consumed handoff means the evidence lane is still unresolved.\n- Do not interrupt or shut down subagent work before the handoff has been written or explicitly reported as `BLOCKED` or `NEEDS_CONTEXT`.\n- Use `wait_agent` only after the current investigation fan-out reaches its join point.\n- Use `close_agent` after integrating finished subagent results.\n- Do not resolve the session directly from successful automated verification. Successful automated verification must hand off into formal human verification.\n- If human feedback reports another problem, classify it as `same_issue`, `derived_issue`, or `unrelated_issue`.\n- Default to `same_issue` unless strong evidence proves the other classes.\n- Keep fixing, agent verification, `awaiting_human_verify`, and final session resolution on the leader path.\n",{"name":5,"metadata":24,"description":7,"compatibility":27},{"author":25,"source":26},"github-spec-kit","templates\u002Fcommands\u002Fdebug.md","Requires spec-kit project structure with .specify\u002F directory","main","021f5cbe02157229460a577e9a585f2da6d78cb0",".codex\u002Fskills\u002Fsp-debug","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck","https:\u002F\u002Fgithub.com\u002Fchenziyang110","2026-08-07 18:10:54",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add chenziyang110\u002Flaunchdeck --skill sp-debug",{"tool":40,"command":41},"bunx","bunx skills add chenziyang110\u002Flaunchdeck --skill sp-debug",{"tool":43,"command":44},"pnpm","pnpm dlx skills add chenziyang110\u002Flaunchdeck --skill sp-debug","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002FSKILL.md",true,[48,54,58,62,66,70,74,78],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fdebug-state.md","REFERENCE","参考文档",5509,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Fdebug-state.md",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Ffix-gate.md",14476,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Ffix-gate.md",{"path":59,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Fhypothesis-and-root-cause.md",11009,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Fhypothesis-and-root-cause.md",{"path":63,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002FINDEX.md",1496,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002FINDEX.md",{"path":67,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fintake-and-debug-checkpoint.md",55303,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Fintake-and-debug-checkpoint.md",{"path":71,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fregression-validation-and-closeout.md",2460,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Fregression-validation-and-closeout.md",{"path":75,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Freproduction-and-evidence.md",21076,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Freproduction-and-evidence.md",{"path":79,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Fsemantic-work-contract.md",32432,"https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsp-debug\u002Freferences\u002Fsemantic-work-contract.md",[83,90,96,102,109,118],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7875F3HQ1GF5F6BR36KY3JE","launchdeck-agent","Codex host adapter contract fixture for Launchdeck.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fagent-hosts\u002Fcodex\u002Fskill\u002FSKILL.md",[],[],{"skillNo":91,"name":85,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7875DV2DQR33K1NFJHKAMZP","Claude host adapter contract fixture for Launchdeck.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fagent-hosts\u002Fclaude\u002Fskill\u002FSKILL.md",[],[],{"skillNo":97,"name":85,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M78759JQ7A6FQ8KDQTNYS3X9","Use this skill aggressively for local project lifecycle operations even when the user does not mention Launchdeck: start this project, run the dev server, dev, build, test, restart service, stop service, show logs, inspect ports, port is occupied, clean cache; and when the user explicitly asks to configure this local project for Launchdeck or create or generate a project-adapted `.launchdeck.yml`, including 为这个项目生成 Launchdeck 配置. Do not use for ordinary code edits, docs-only work, general explanations, API design discussion, or production deployment unless the user also asks to operate or configure a local project or service.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002Fagent\u002Finstaller-payload\u002Fskill\u002Flaunchdeck-agent\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":19},"01M78753ZJQ7G2CZT1W1G8WRJV","zig-testing","Use ONLY when user explicitly requests Zig test code, built-in test runner configuration,\ntest failure diagnosis, or coverage for Zig projects.\n\nTriggers: \"write test zig\", \"zig test\", \"testing.allocator\", \"zig coverage\",\n\"comptime test\", \"zig expectError\", \"zig snapshot test\", \"zig fuzz\".\n\nDo NOT activate for: general Zig coding without test context, build.zig configuration\nfor non-test targets, Zig compiler errors, or Zig build system setup.","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fzig-testing\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":113,"licenseFileUrl":114,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":19},"01M78750JXY4Z5D5W1EX3PQ31Z","webapp-testing","Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":19},"01M7874X2T83EQQFRCEY5SJJVC","verification-before-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002Fchenziyang110\u002Flaunchdeck\u002Fblob\u002Fmain\u002F.specify\u002Ftemplates\u002Fpassive-skills\u002Fverification-before-completion\u002FSKILL.md",[],[]]