sp-deep-research
Use when a planning-ready spec still has feasibility risk and needs coordinated research, evidence packets, or disposable demo spikes before implementation planning.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sp-deep-research
- metadata
- { "author": "github-spec-kit", "source": "templates/commands/deep-research.md" }
- description
- Use when a planning-ready spec still has feasibility risk and needs coordinated research, evidence packets, or disposable demo spikes before implementation planning.
- argument-hint
- Describe the feasibility question, research tracks, or demo proof needed before planning handoff
- compatibility
- Requires spec-kit project structure with .specify/ directory
- user-invocable
- true
02 资源文件 2
- 参考文档references/INDEX.md616 B
- 参考文档references/semantic-work-contract.md31.5 KB
03 SKILL.md 正文
Invocation Syntax
- In this integration, invoke workflow skills with
/sp-plan-style syntax. - References such as
/sp.plan,/sp.tasks, ornext_command: /sp.planare canonical workflow-state identifiers and handoff values. - Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.
Workflow Contract Summary
- When to use: The current spec package exists, but one or more capabilities do not yet have a credible implementation chain.
- Primary objective: Coordinate focused research and isolated prototype evidence, synthesize implementation-chain decisions, and produce a planning handoff before /sp-plan.
- Primary outputs:
FEATURE_DIR/deep-research.mdwithPlanning Handoff, optionalFEATURE_DIR/research-spikes/, updatedalignment.md,context.md,references.md, andworkflow-state.md. - Default handoff: /sp-plan when feasibility is proven or explicitly accepted; otherwise /sp-clarify for requirement gaps or stop with blocked research risks.
- Execution note: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.
Blocked Exit Contract
If blocked after safe recovery, read and follow
.specify/templates/workflow-blocker-template.md and its JSON schema. Never
return only an error or “ask a human”; preserve state and keep agent-capable
repair agent-owned. Set human_action_required: true only for authority,
credentials, protected systems, human decisions/reviews, or physical access.
Tailor steps, expected results, failure paths, evidence, and resume action to
CI, visual review, or product decisions. Never claim completion.
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Objective
Produce a planning-ready research packet before implementation planning starts:
prove or retire planning-critical feasibility questions, synthesize external and
repository evidence, validate uncertain links with disposable demo spikes when
needed, and hand /sp.plan the constraints and recommended implementation
direction it must preserve.
Context
- Primary inputs: the current spec package, unresolved feasibility risks, external references, repository evidence, research-agent findings, and any disposable prototype evidence created in this command.
- The active working set is
spec.md,alignment.md,context.md,references.md,deep-research.md,research-spikes/, andworkflow-state.mdinside the currentFEATURE_DIR. - This command is research-only. It is not permission to implement production behavior.
Process
- Decide whether a feasibility and research handoff gate is actually needed.
- Decompose unknown implementation chains by capability and independent research track.
- Dispatch subagents when independent research tracks can run in parallel and produce evidence packets without conflicting writes.
- Research external APIs, libraries, algorithms, platform constraints, and repository patterns only where those facts change planning.
- Build the smallest disposable demo or spike when research alone cannot prove the chain.
- Synthesize research-agent findings and spike results into planning decisions,
rejected options, risks, and a concrete
/sp.planhandoff. - Run reverse coverage validation before handoff: every CAP → PH → Evidence chain must close.
- Run readiness refusal checks; refuse handoff with a gap report when checks fail.
- Run the Planning Handoff Readiness Checklist; do not recommend
/sp.planuntil all items pass.
Output Contract
- Write or update
deep-research.md. - Optionally write isolated scratch assets under
research-spikes/. - Update
alignment.md,context.md,references.md, andworkflow-state.mdwhen feasibility evidence changes planning readiness. - If this gate is not needed, still write a lightweight
deep-research.mdwith**Status**: Not needed,Feasibility Decision,Planning Handoff, andNext Command; do not inventCAP/TRK/EVD/PHIDs for already-proven work. - Include a
Planning Handoffsection that/sp.plancan consume directly for recommended approach, module boundaries, API/library choices, demo artifacts, constraints, rejected options, and residual risks. - Use stable traceability IDs (
CAP-###,TRK-###,EVD-###,SPK-###,PH-###) plus an evidence quality rubric so/sp.plancan cite exactly which research finding or spike supports each design decision. - Use
.specify/templates/examples/deep-research/as the output-shape reference when available:not-needed.md,docs-only-evidence.md, andspike-required.md. - Report which capabilities are proven, constrained, blocked, or no longer worth planning.
- Persist accepted evidence packets as
FEATURE_DIR/research-evidence/<EVD-###>.json.
Guardrails
- Do not edit production source files, tests, migrations, release config, or
implementation artifacts from
sp-deep-research. - Keep demos disposable and isolated under
FEATURE_DIR/research-spikes/unless the user explicitly asks to preserve a prototype elsewhere in a later implementation workflow. - Skip this command when the change is a minor adjustment to an existing, already-proven capability.
- Do not let research subagents edit production files; they must either return evidence packets or write only to their assigned disposable spike directory.
- A research pass without runnable evidence (spike result or repo path trace) is a failed pass.
- Coordinator-only execution without subagent dispatch justification and recorded
subagent-blockedreason is a failed pass. - Feasibility claims based only on documentation citations without live repository path reads are not sufficient for planning.
- Subagent evidence packets without
paths_readmust be rejected; do not accept or synthesize them. - A structural-only refresh (reformatting findings without new evidence) is a failed pass.
- Treat
context.mdLocked Decisions as immutable constraints during research. Do not research alternatives that contradict a locked decision unless the research explicitly proves the locked decision is infeasible, in which case mark the affected CAP asblockedand escalate; do not silently replace the locked decision.
Senior Consequence Analysis Gate
Run 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.
Project 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.
Project cognition readiness provides routing advice. 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, continue with live repository evidence and recommend /sp-map-scan -> /sp-map-build only for brownfield first/missing/unusable 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/runtime 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 project-cognition mark-dirty only as fallback when inline update cannot complete. sp-map-update is for manual/external 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/external maintenance and ordinary existing-baseline gaps.
Required output when the gate triggers:
- Affected Object Map: name each object, record, worker, queue, artifact, command, API, file surface, user-visible state, or downstream consumer that can be affected.
- 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.
- Dependency Impact Table: map direct dependencies, indirect consumers, shared state, compatibility surfaces, validation routes, and adjacent workflows that can break if semantics change.
- Recovery And Validation Contract: state rollback, retry, idempotency, cleanup, migration, observability, and validation evidence required before handoff or completion.
- 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.
- Consequence Obligations: assign stable
CA-###IDs to every obligation that must survive downstream handoff, task generation, worker packets, verification, or debug closeout. EachCA-###must include claim, affected objects, owner workflow, latest resolve phase, status, and stop-and-reopen condition.
Stand 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.
If 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.
[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read references/semantic-work-contract.md.
Detailed References
Read Reference index before applying shared semantic contracts.
Mandatory Subagent Execution
All substantive tasks in ordinary sp-* workflows default to and must use subagents.
The leader orchestrates: route, split tasks, prepare task contracts, dispatch subagents, wait for structured handoffs, integrate results, verify, and update state.
Before dispatch, every subagent lane needs a task contract with objective, authoritative inputs, allowed read/write scope, forbidden paths, acceptance checks, verification evidence, and structured handoff format.
Use execution_model: subagent-mandatory.
Use dispatch_shape: one-subagent | parallel-subagents.
Use execution_surface: native-subagents.
Pre-Execution Checks
Check for extension hooks (before deep research):
- Check if
.specify/extensions.ymlexists in the project root. - If it exists, read it and look for entries under the
hooks.before_deep_researchkey. - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.
- Filter out hooks where
enabledis explicitlyfalse. Treat hooks without anenabledfield as enabled by default. - For each remaining hook, do not attempt to interpret or evaluate hook
conditionexpressions:- If the hook has no
conditionfield, or it is null/empty, treat the hook as executable. - If the hook defines a non-empty
condition, skip the hook and leave condition evaluation to the HookExecutor implementation.
- If the hook has no
- For each executable hook, output the following based on its
optionalflag:- Optional hook (
optional: true):## Extension Hooks **Optional Pre-Hook**: {extension} Command: `/{command}` Description: {description} Prompt: {prompt} To execute: `/{command}` - Mandatory hook (
optional: false):## Extension Hooks **Automatic Pre-Hook**: {extension} Executing: `/{command}` EXECUTE_COMMAND: {command} Wait for the result of the hook command before proceeding to the Outline.
- Optional hook (
- If no hooks are registered or
.specify/extensions.ymldoes not exist, skip silently.
Maintain workflow quality without hook choreography:
- Confirm project cognition freshness and valid workflow entry before deeper research begins.
- Keep
workflow-state.mdcurrent as the durable source of truth for phase, allowed artifact writes, next action, and exit criteria. - Verify the final
deep-research.mdandworkflow-state.mdoutputs before handoff instead of relying on chat narration. - Update durable state before compaction-risk transitions, prototype-evidence synthesis handoffs, or any stop where resume will depend on more than the visible conversation.
Project Learning
The CLI is the only agent-facing Learning read surface:
- Run
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning start --command <classic-command-name> --format jsonbefore deeper non-trivial work. - Select summaries by applicability and triggers; use
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning list --command <classic-command-name> --format jsononly to filter or page. - Execute one matching card's
show_argv. Do not parse Learning storage.
start, list, and show are read-only. Current repository evidence,
.specify/memory/constitution.md, and explicit user direction override stale or
candidate Learning.
At closeout, corrections, retries, route changes, recovery, false leads, hidden
dependencies, validation/tooling/state/cognition gaps, constraints, and near
misses are capture signals. Prefer uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify learning capture-auto
from owning state; manual capture includes summary, problem, action, triggers,
success criteria, avoid items, exceptions, and evidence.
fast: skip unless the task escalates.accept,analyze,ask,auto,constitution,explain,implement-teams,taskstoissues, andteam: consume-only; do not violate their write boundaries to capture.- Other non-trivial workflows: consume before deeper work; capture reusable signals at closeout or record a no-learning decision.
The policy returned by the CLI is authoritative when prompt wording drifts.
Workflow Phase Lock
- [AGENT] Create or resume
WORKFLOW_STATE_FILEbefore substantial research. - Read
.specify/templates/workflow-state-template.md. - If
WORKFLOW_STATE_FILEalready exists, read it first and preserve still-validnext_action,exit_criteria, andnext_commanddetails instead of relying on chat memory alone. - Treat
WORKFLOW_STATE_FILEas the stage-state source of truth on resume after compaction for the current command, allowed artifact writes, forbidden actions, authoritative files, next action, and exit criteria. - Set or update the state for this run with at least:
active_command: sp-deep-researchphase_mode: research-onlyallowed_artifact_writes: deep-research.md, research-spikes/, alignment.md, context.md, references.md, workflow-state.mdforbidden_actions: edit production source code, edit tests, fix build/tooling, implement behavior, commit prototype code as productionauthoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.mdtrack_exit_states: per TRK-### exit stateevidence_packet_acceptance: accepted and rejected packet lists with reasonsfailed_readiness_checks: list of check IDs that failedopen_gaps: gap ID, description, severity, and linked CAP/TRK IDsentry_source:sp-specify|sp-clarify(which command routed here)research_mode:full-research|supplement-research
- Do not edit production code, production tests, migrations, release config, or implementation artifacts from
sp-deep-research. - When resuming after compaction, re-read
WORKFLOW_STATE_FILEbefore proceeding.
Multi-Agent Research Orchestration
-
[AGENT] Treat the current session as the research coordinator. The coordinator owns scope control, join points, conflict resolution, and the final
deep-research.mdsynthesis. -
[AGENT] Before delegating, split the feasibility problem into independent research tracks only when the tracks can run in parallel without sharing write targets. Good tracks include:
- repository implementation-pattern evidence
- external API/library/platform feasibility
- data shape, migration, permission, performance, or integration constraints
- alternative approach comparison
- disposable demo/spike validation
-
[AGENT] Dispatch subagents when independent tracks can run in parallel and that materially improves evidence quality or speed. When the next coordinator decision is blocked on a single tightly coupled fact, either create one safe packetized evidence lane for that fact or stop for escalation/recovery with the blocker recorded.
-
[AGENT] Give each subagent one bounded track, one expected output shape, and one write scope. Research-only subagents should return evidence packets in their final response. Demo/spike subagents may write only under
FEATURE_DIR/research-spikes/<track-slug>/. -
[AGENT] Do not duplicate work across subagents. If two tracks overlap, assign one owner and ask the other to focus on a distinct risk or alternative.
-
[AGENT] Require every subagent to return an evidence packet with:
trackquestionsources_or_repo_evidencefindingconfidence: high | medium | lowplanning_implicationsconstraints_for_sp_planrejected_optionsresidual_risksspike_artifactswhen applicable
-
[AGENT] After each subagent returns, apply the evidence packet acceptance protocol:
- ACCEPT when:
paths_readis non-empty,findingis specific and evidence-backed, core question is answered, and no production files were edited. - REJECT when:
paths_readis empty or missing,findingis empty or only speculative, core question is unanswered, or the subagent edited production source files. - Record every acceptance and rejection in
workflow-state.md. - For rejected packets: retry once with clarified instructions. If the retry also fails, mark the track as
blocked, recordsubagent-blockedwith the rejection reason, and escalate. - Do not silently ignore or synthesize rejected evidence packets.
## Evidence Packet Acceptance | Track | Subagent | Status | Reason if Rejected | Action | |-------|----------|--------|--------------------|--------| | TRK-001 | agent-1 | ACCEPTED | — | — | | TRK-002 | agent-2 | REJECTED | No paths_read | Retry once | | TRK-003 | agent-3 | REJECTED | Edited source file | BLOCKED, escalate | - ACCEPT when:
-
[AGENT] Join all subagent results before writing final conclusions. Resolve contradictions by preferring runnable spike evidence, current repository evidence, primary documentation, then secondary sources in that order. Mark conflicts that remain unresolved instead of hiding them.
-
[AGENT] The coordinator must convert subagent packets into
Research Agent Findings,Synthesis Decisions, andPlanning Handoff; do not paste raw subagent output as the final artifact. -
[AGENT] After accepting a subagent evidence packet, persist it as
FEATURE_DIR/research-evidence/<EVD-###>.jsonwith the full evidence packet fields plus the evidence quality rubric. This enables:- independent audit without re-parsing
deep-research.md - direct citation by
/sp.planvia evidence ID - safe context-compaction recovery
- independent audit without re-parsing
-
[AGENT] If subagent dispatch is unavailable or unsafe, record the decision as
subagent-blockedwith the concrete reason, preserve the decomposed tracks as blocked work, and stop for escalation or recovery instead of continuing as coordinator-only execution.
Traceability and Evidence Quality Contract
- Assign stable IDs before running research so later planning can cite specific evidence instead of paraphrasing it:
- capability IDs:
CAP-001,CAP-002, ... - research track IDs:
TRK-001,TRK-002, ... - evidence IDs:
EVD-001,EVD-002, ... - spike IDs:
SPK-001,SPK-002, ... - Planning Handoff item IDs:
PH-001,PH-002, ...
- capability IDs:
- Use the IDs consistently across
Capability Feasibility Matrix,Research Agent Findings,Implementation Chain Evidence,Demo / Spike Evidence,Synthesis Decisions, andPlanning Handoff. - Every handoff item must trace back to at least one evidence ID, spike ID, repository path, or source reference.
- Grade each evidence item using this rubric:
- Source tier:
repo-evidence | runnable-spike | primary-docs | official-example | standard | secondary-source | inference - Reproduced locally:
yes | no | not applicable - Recency: [date, version, or
not time-sensitive] - Confidence:
high | medium | low - Plan impact:
blocking | constraining | informative - Limitations: [what the evidence does not prove]
- Source tier:
- Stop each research track when it reaches one of these exit states:
enough-to-planconstrained-but-plannableblockednot-viableuser-decision-requiredstale-needs-revalidation— prior evidence may no longer be valid due to dependency or platform changes
- Do not continue researching a track once it has enough evidence to support a planning decision. Convert the result into a handoff item and move on.
- For every spike, record the reproducibility contract:
- hypothesis
- setup/env
- command
- expected result
- actual result
- cleanup note
- what this does not prove
Outline
-
Setup: Run
.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnlyfrom repo root once (--json --paths-only/-Json -PathsOnly). Parse:- If
FEATURE_DIRis not already explicit, preferuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@4a631657f75460886dbd12ebe48b14fc11cfe0bf specify lane resolve --command deep-research --ensure-worktreebefore guessing from branch-only context. - When lane resolution returns a materialized lane worktree, continue research from that isolated worktree context instead of assuming the leader workspace already matches the active feature lane.
FEATURE_DIRFEATURE_SPEC- optional downstream paths if returned
- If JSON parsing fails, abort and instruct the user to verify the feature branch environment.
- Set
ALIGNMENT_FILEtoFEATURE_DIR/alignment.md. - Set
CONTEXT_FILEtoFEATURE_DIR/context.md. - Set
REFERENCES_FILEtoFEATURE_DIR/references.md. - Set
DEEP_RESEARCH_FILEtoFEATURE_DIR/deep-research.md. - Set
SPIKES_DIRtoFEATURE_DIR/research-spikes. - Set
WORKFLOW_STATE_FILEtoFEATURE_DIR/workflow-state.md.
- If
-
Create or resume the workflow state:
- Read
.specify/templates/workflow-state-template.md. - If
WORKFLOW_STATE_FILEalready exists, read it first and preserve still-validnext_action,exit_criteria, andnext_commanddetails instead of relying on chat memory alone. - Determine entry source:
- If the prior
active_commandinworkflow-state.mdwassp-specify→entry_source: sp-specify,research_mode: full-research - If the prior
active_commandwassp-clarify→entry_source: sp-clarify,research_mode: supplement-research - If undetermined → default to
full-research
- If the prior
- In
supplement-researchmode, preserve existing evidence and only research newly added or changed capabilities. - Record entry source and research mode in
deep-research.mdResearch Orchestration section. - Persist at least:
active_command: sp-deep-researchphase_mode: research-onlyallowed_artifact_writes: deep-research.md, research-spikes/, alignment.md, context.md, references.md, workflow-state.mdforbidden_actions: edit production source code, edit tests, fix build/tooling, implement behavior, commit prototype code as productionauthoritative_files: spec.md, alignment.md, context.md, references.md, deep-research.md
- Read
-
Load current spec package and repository context:
-
FEATURE_SPEC -
FEATURE_DIR/alignment.md -
FEATURE_DIR/context.md -
FEATURE_DIR/references.mdif present -
FEATURE_DIR/deep-research.mdif present -
.specify/memory/constitution.mdif present -
.specify/memory/project-rules.mdif present -
compact
learning start --command deep-researchresults and only selectedlearning showrecords -
Project cognition gate: query the active project's runtime before broad repository reads.
Run or emulate:
C:\Users\11034\.specify\bin\project-cognition.exe compass --intent research --query=\"$ARGUMENTS\" --format jsonAfter the default compass packet, run the advanced
lexicon -> semantic_intake -> querypath only whencompass_state, coverage diagnostics, localization, or live evidence requires explicit concept decisions. In that escalation, useproject-cognition lexicon --mode catalogas the alias catalog, write agent-authoredsemantic_intakeandconcept_decisions, then runproject-cognition query --query-plan "<query_plan_json>"; includequery_plan,semantic_intake,concept_decisions,covered_facets,missing_facets,match_sources,lexicon_generation_id,repository_search_terms, project-language search terms, and facet coverage; do not search only the raw user words before source search. Agent-owned semantic normalization remains mandatory:agent_normalizationand raw lexicon ranking are bootstrap signals only; ifagent_normalizationis omitted, treat it asrequired=false; usewrite_semantic_intake_from_alias_catalogwhen needed. Raw lexicon ranking is only a bootstrap; CJK or mixed CJK/ASCII input still requires agent-owned normalization even when positive raw lexical matches exist. The agent still owns translation. Readiness values arequery_ready,review,needs_rebuild,blocked, andunsupported_runtime.Use the returned readiness:
query_ready: read top-levelminimal_live_readsfirst, then use lane-levelfirst_pass_pathsreasons.review: perform only the returnedminimal_live_readsbefore continuing and inspectcoverage_diagnostics.blocked: report the blocking runtime issue and continue with live evidence only where this workflow allows degraded navigation.- CARRY FORWARD: Treat project-cognition results as repository-grounded
starting context. Preserve cited capabilities, constraints, affected
surfaces, and verification routes in
deep-research.md, and distinguish repository facts from external research findings.
-
From
FEATURE_DIR/alignment.md, extract:Feasibility / Deep Research Gatestatus per capabilityPlanning Gate Recommendation- Capabilities marked
Needed before plan→ these are the research targets - Capabilities marked
Not neededorCompleted→ skip, do not research - Capabilities marked
Blocked→ preserve blocker, record reason, do not research unless unblocked
-
targeted live files only when the project cognition runtime cannot prove the current implementation pattern
-
external docs, API references, release notes, examples, or research material when they materially affect feasibility
-
3b. Detect staleness and prior evidence:
- If FEATURE_DIR/deep-research.md already exists from a prior run, compare
new findings against prior conclusions.
- For each CAP with prior evidence, check whether dependencies (library
versions, API endpoints, platform behavior) have changed since the last
research pass.
- Mark CAPs with potentially stale evidence as stale-needs-revalidation
and prioritize their research tracks.
- Record staleness triggers (version bumps, deprecation notices, etc.) in
the track description.
```markdown
## Differential Evidence Analysis
| CAP ID | Previous Conclusion | Previous Evidence | New Evidence | Status Change |
|--------|--------------------|--------------------|--------------|---------------|
| CAP-001 | proven | EVD-001 | EVD-005 confirms | Unchanged |
| CAP-002 | constrained | EVD-002 | SPK-003 disproves | **OVERTURNED** → blocked |
| CAP-003 | proven (2026-03) | EVD-004 | lib X v3→v4 | **STALE** → revalidate |
```
-
Decide whether this gate is needed:
- Skip deep research and recommend
/sp.planwhen all target capabilities already have a known implementation path in the repository or the work is only a minor adjustment to existing behavior. - When skipping, still write a lightweight
deep-research.mdusing**Status**: Not needed,Feasibility Decision,Planning Handoff, andNext Command; do not inventCAP/TRK/EVD/PHIDs for work that is already proven. - Continue when any capability depends on an unproven API, library, algorithm, platform behavior, data volume, permission boundary, external integration, performance envelope, generated-code workflow, native/plugin bridge, or other path where planning would otherwise guess.
- If the uncertainty is a requirement gap rather than feasibility risk, recommend
/sp.clarifyand updateworkflow-state.mdwith that route reason.
- Skip deep research and recommend
-
Build a capability feasibility matrix from the spec's capability decomposition:
- Start from the capability list in
spec.md. Each spec capability maps to one CAP-###. - Do not invent new capability names; use the spec's decomposition as the source of truth.
- If a spec capability is too broad for focused research, split it into sub-capabilities (CAP-001a, CAP-001b) and note the split in
alignment.md. - For each capability, read its feasibility status from
alignment.mdand take action:
Alignment Status Action Needed before planCreate research track, assign TRK-### Not neededMark provenornot needed, skipCompletedPreserve existing evidence, skip BlockedRecord blocker, do not research - Start from the capability list in
5b. Consequence-Sensitive Research Tracks:
- If the Senior Consequence Analysis Gate is triggered or upstream artifacts carry
CA-###consequence obligations, create research tracks for any unproven affected object, state-behavior matrix entry, dependency impact, recovery behavior, validation route, or coverage gap that planning would otherwise guess. - Each consequence-sensitive
TRK-###must name the linkedCA-###obligation, the stop-and-reopen condition it can clear or confirm, the evidence needed, and the downstream workflow that must consume the result. - Research outputs must not drop
CA-###consequence obligations; carry them intoPlanning Handoff,Synthesis Decisions,Validation implications, and residual risks until they are resolved or explicitly deferred. - If evidence disproves an upstream consequence assumption, preserve the obligation as blocked, record the stop-and-reopen condition, and route back to
/sp.clarifyinstead of handing ambiguous semantics to/sp.plan. - When a consequence obligation is proven enough for planning, record the evidence ID, affected objects, lifecycle states covered, dependency impact, recovery and validation contract, remaining coverage gaps, and whether the obligation is still open.
For each capability or module slice, record:
- stable capability ID (
CAP-###) — mapped from spec capability name - capability name (from spec.md)
- desired outcome (from spec.md)
- current evidence from the repository
- unknown implementation-chain link
- research questions
- independent research track owner when delegation is useful
- whether a disposable demo is required
- proof target: what evidence would be enough to plan safely
- result status:
proven,constrained,not viable,blocked, ornot needed
Before finalizing the matrix, check each CAP against the preset research dimensions. At minimum, confirm or mark "not applicable" for:
- permissions / auth boundary
- data volume / performance envelope
- error / exception / rollback flow
- concurrency / consistency
- logging / observability
- migration / compatibility
- external dependency SLO / failure mode
- template / generated-code propagation
- minimum verifiable test path
-
Select the research dispatch shape:
- [AGENT] Before research fan-out begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract:
choose_subagent_dispatch(command_name="deep-research", snapshot, workload_shape). - Persist the decision fields exactly:
execution_model: subagent-mandatory,dispatch_shape: one-subagent | parallel-subagents,execution_surface: native-subagents. - Decision order is fixed:
- One safe validated track ->
one-subagentonnative-subagentswhen available. - Two or more safe isolated tracks ->
parallel-subagentsonnative-subagentswhen available. - No safe lane, overlapping write scopes, missing contract, or unavailable delegation ->
subagent-blockedwith a recorded reason.
- One safe validated track ->
- For
deep-research, safe fan-out means at least two independent research tracks with disjoint write scopes. Research-only tracks return evidence packets; demo tracks write only under their assignedFEATURE_DIR/research-spikes/<track-slug>/. - Required join points:
- before final conflict resolution
- before writing
Synthesis Decisions - before writing
Planning Handoff
- Record the chosen strategy, reason, any
subagent-blockedcondition, selected research tracks, write scopes, and join points indeep-research.md. - Keep the shared workflow language integration-neutral. Do not present Codex-only runtime surface wording in this shared template.
- [AGENT] Before research fan-out begins, assess workload shape and the current agent capability snapshot, then apply the shared policy contract:
-
Plan and run coordinated research:
- Create research tracks from the capability matrix before searching broadly.
- For each track, assign a stable track ID (
TRK-###) and define the exact question, evidence target, likely sources, whether a spike is needed, and how the result will affect/sp.plan. - If two or more tracks are independent and subagent dispatch is available, dispatch bounded subagents according to the Multi-Agent Research Orchestration contract.
- If subagent dispatch is unavailable or low-confidence, record
subagent-blocked, capture which tracks could not be dispatched, and stop before substantive research until the block is resolved or explicitly escalated. - Search and read only sources that answer a named feasibility question.
- Prefer primary docs, official examples, standards, changelogs, release notes, library docs, code examples from the dependency itself, and current repository evidence.
- Cite external sources in
references.mdand summarize how each source affects the implementation chain. - Separate facts from inference. If one source is weak or unverified, say so.
- Preserve rejected alternatives with explicit reasons when they matter to planning.
- Convert every completed track into an evidence packet with stable evidence IDs (
EVD-###), evidence quality ratings, limitations, and a track exit state.
-
Run isolated demo validation when needed:
- Assign a stable spike ID (
SPK-###) and create the smallest runnable spike underSPIKES_DIRwhen docs and repository evidence cannot prove feasibility. - Keep the spike intentionally disposable: no production imports unless read-only, no edits outside
FEATURE_DIR/research-spikes/, no migration or test-suite changes. - Define the spike before writing it:
- hypothesis
- inputs / fixture data
- setup/env
- expected pass condition
- commands to run
- actual result capture format
- cleanup or non-persistence note
- what this does not prove
- Run the spike command if the local environment supports it.
- Capture command, exit status, relevant output summary, and evidence path in
deep-research.md. - If the environment cannot run the spike, record exactly what is missing and whether planning can still proceed with a manual-risk note.
- Assign a stable spike ID (
-
Synthesize research into planning decisions:
- Compare evidence packets across tracks.
- Resolve conflicts and record why one source or demo result won over another.
- Record every conflict and its resolution in the
Contradiction Resolution Log. - Unresolved conflicts must be marked
BLOCKEDand escalated; do not hide them. - Identify the recommended approach, rejected approaches, and constraints
/sp.planmust preserve. - Translate demo observations into planning implications rather than leaving them as raw logs.
- Identify module boundaries, API/library choices, data flow notes, operational constraints, and validation implications that planning must account for.
- Assign stable Planning Handoff IDs (
PH-###) to each decision or constraint that/sp.planmust consume.
-
Write
deep-research.md: Use.specify/templates/examples/deep-research/as the output-shape reference when available:
not-needed.mdfor**Status**: Not neededdocs-only-evidence.mdwhen repository evidence and primary documentation are enoughspike-required.mdwhen a disposable demo proves the implementation chain
Use the lightweight structure below only when the gate is not needed:
# Deep Research: [FEATURE NAME]
**Feature Branch**: `[###-feature-name]`
**Created**: [DATE]
**Status**: Not needed
## Feasibility Decision
- **Recommendation**: Proceed to `/sp.plan`
- **Reason**: [Why repository evidence already proves the implementation chain]
- **Planning handoff readiness**: Not needed
## Planning Handoff
- **Handoff IDs**: Not needed
- **Status**: All capabilities have proven implementation chains in repository
- **Recommended approach**: [Existing implementation path `/sp.plan` should use]
- **Constraints `/sp.plan` must preserve**: [Existing boundary, behavior, or constraint]
- **PH items**: None (all capabilities proven — no research-generated handoff items)
## Planning Handoff Readiness Checklist
- [ ] All capabilities have proven implementation chains in repository
- [ ] `alignment.md` updated with `Not needed` feasibility status
- [ ] `context.md` updated
- [ ] `workflow-state.md` updated with `next_command: /sp.plan`
## Next Command
- `/sp.plan`
Use the full structure below when any capability needed research, evidence, or a disposable spike:
# Deep Research: [FEATURE NAME]
**Feature Branch**: `[###-feature-name]`
**Created**: [DATE]
**Status**: [Ready for plan | Ready for plan with constraints | Blocked | Not needed]
## Feasibility Decision
- **Recommendation**: [Proceed to `/sp.plan` | Proceed with constraints | Run `/sp.clarify` | Stop / redesign]
- **Reason**: [Short evidence-based rationale]
- **Planning handoff readiness**: [Complete | Complete with constraints | Incomplete]
## Capability Feasibility Matrix
| Capability ID | Capability | Unknown Link | Evidence Needed | Proof Method | Result |
| --- | --- | --- | --- | --- | --- |
| CAP-001 | [Name] | [What was uncertain] | [Proof target] | [docs / repo evidence / demo] | [proven / constrained / blocked / not needed] |
## Research Orchestration
- **Execution model**: subagent-mandatory
- **Dispatch shape**: [one-subagent | parallel-subagents | subagent-blocked]
- **Execution surface**: native-subagents
- **Reason**: [safe-one-subagent | safe-parallel-subagents | native-subagents-supported | no-safe-delegated-lane | unsafe-write-sets | packet-not-ready | runtime-no-subagents | low-delegation-confidence]
- **Selected tracks**:
- [track] -> [research-only evidence packet | demo spike write scope]
- **Join points**:
- before final conflict resolution
- before writing `Synthesis Decisions`
- before writing `Planning Handoff`
## Research Agent Findings
| Track ID | Agent / Mode | Question | Evidence IDs | Confidence | Exit State | Planning Implication |
| --- | --- | --- | --- | --- | --- | --- |
| TRK-001 | [child agent name or subagent-blocked status] | [Question] | EVD-001, SPK-001 | [high / medium / low] | [enough-to-plan / constrained-but-plannable / blocked / not-viable / user-decision-required] | [What `/sp.plan` must use] |
## Evidence Quality Rubric
| Evidence ID | Supports | Source Tier | Source / Path | Reproduced Locally | Recency / Version | Confidence | Plan Impact | Limitations | Persisted |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| EVD-001 | CAP-001 / PH-001 | [repo-evidence / runnable-spike / primary-docs / official-example / standard / secondary-source / inference] | [URL, file path, or spike path] | [yes / no / not applicable] | [date/version/not time-sensitive] | [high / medium / low] | [blocking / constraining / informative] | [what this does not prove] | research-evidence/EVD-001.json |
## Implementation Chain Evidence
### [Capability Name]
- **Capability ID**: CAP-001
- **Chain**: [trigger/input -> module/API/library -> state/output -> validation]
- **Repository evidence**: [EVD IDs, files, patterns, existing behavior]
- **External evidence**: [EVD IDs, source links or references.md entries]
- **Demo evidence**: [SPK IDs, spike path and command result, or not needed]
- **Planning constraints**: [rules `/sp.plan` must preserve]
- **Residual risk**: [remaining uncertainty]
## Demo / Spike Evidence
- **Spike ID**: SPK-001
- **Spike**: [name]
- **Hypothesis**: [what it proves]
- **Path**: `research-spikes/[name]`
- **Setup / env**: [runtime, dependency, fixture, credentials placeholder, or not required]
- **Command**: `[command]`
- **Expected result**: [observable pass condition]
- **Actual result**: [passed / failed / not run, with summary]
- **Evidence summary**: [short result]
- **Cleanup note**: [what remains disposable or how to remove it]
- **What this does not prove**: [limits of the spike]
- **Planning implication**: [what design or validation decision follows]
## Spike Log
- **Spike**: [name]
- **Hypothesis**: [what it proves]
- **Path**: `research-spikes/[name]`
- **Command**: `[command]`
- **Result**: [passed / failed / not run]
- **Evidence summary**: [short result]
## Synthesis Decisions
- **Recommended approach**: [PH-001 -> approach and why]
- **Rejected options**:
- [option] -> [evidence-based reason and evidence IDs]
- **Conflict resolution**:
- [conflict] -> [resolution and evidence priority]
- **Plan constraints**:
- PH-### -> [constraint `/sp.plan` must preserve]
## Contradiction Resolution Log
When two or more evidence items produce conflicting findings, record the
resolution. Unresolved contradictions must be marked `BLOCKED` and escalated.
| Conflict | Evidence A | Evidence B | Resolution | Priority Basis | Suppressed Reason |
|----------|-----------|-----------|------------|----------------|-------------------|
| [e.g. API version] | EVD-002: v3 | EVD-005: v2 | v3 accepted | spike > docs | EVD-005 was outdated |
| [unresolved] | EVD-007: pattern A | SPK-003: pattern B | **BLOCKED** | — | Contradictory runnable evidence |
## Planning Handoff
- **Handoff IDs**: PH-001, PH-002, ...
- **Recommended approach**: PH-001 -> [implementation direction `/sp.plan` should start from; trace to CAP/TRK/EVD/SPK IDs]
- **Architecture implications**: PH-002 -> [components, layering, boundaries, sequencing; trace to CAP/TRK/EVD/SPK IDs]
- **Module boundaries**: PH-003 -> [owners and interfaces to preserve; trace to CAP/TRK/EVD/SPK IDs]
- **API / library choices**: PH-004 -> [selected APIs/libraries and why; trace to CAP/TRK/EVD/SPK IDs]
- **Data flow notes**: PH-005 -> [inputs, state, outputs, side effects; trace to CAP/TRK/EVD/SPK IDs]
- **Demo artifacts to reference**: PH-006 -> [`research-spikes/...` and command result; trace to SPK IDs]
- **Constraints `/sp.plan` must preserve**:
- PH-### -> [constraint; trace to CAP/TRK/EVD/SPK IDs]
- **Validation implications**: PH-### -> [tests/checks the plan should include later; trace to CAP/TRK/EVD/SPK IDs]
- **Residual risks requiring design mitigation**:
- PH-### -> [risk; trace to CAP/TRK/EVD/SPK IDs]
- **Decisions already proven by research**:
- PH-### -> [decision; trace to CAP/TRK/EVD/SPK IDs]
- **PH consumption contract**:
- `mandatory` — `/sp.plan` must consume this PH; omitting it is a plan error.
- `optional` — `/sp.plan` may defer if the plan does not need it.
- `user-decision` — `/sp.plan` must ask the user before consuming or deferring.
Each PH item in the Traceability Index must carry its consumption contract in
the `Mandatory?` column.
## Capability Cards
For each high-value or planning-critical capability, emit a capability card:
### CAP-001: [Capability Name]
| Field | Detail |
|-------|--------|
| **Purpose** | [What this capability achieves] |
| **Owner** | [Owning module / service / surface] |
| **Truth lives** | [Code path, data table, config, or external service] |
| **Entry points** | [CLI command, API route, event handler, hook] |
| **Downstream consumers** | [What depends on this capability] |
| **Extend here** | [Safe extension points] |
| **Do not extend here** | [Fragile or contract-locked areas] |
| **Key contracts** | [Input shape, output shape, side effects, invariants] |
| **Change propagation** | [What breaks when this changes] |
| **Minimum verification** | [Command or check that proves this works] |
| **Failure modes** | [Known ways this can fail] |
| **Confidence** | [Verified / Inferred / Unknown-Stale] |
## Research Exclusions
Areas, surfaces, or dimensions intentionally not researched in this pass.
| Excluded Area | Reason | Revisit Condition | Recorded By |
|---------------|--------|-------------------|-------------|
| [e.g. performance profiling] | [Not in feature scope] | [Before production deploy] | [Coordinator / TRK-###] |
Every unverified dimension from the preset research checklist that was marked
"not applicable" or "deferred" must appear here with a revisit condition.
## Planning Traceability Index
| PH ID | CAP ID | TRK ID | Evidence IDs | Evidence Quality | Plan Consumer | Required Plan Action | Mandatory? |
|-------|--------|--------|-------------|-------------------|---------------|----------------------|------------|
| PH-001 | CAP-001 | TRK-001 | EVD-001, SPK-001 | HIGH / blocking | architecture | Use pattern X | mandatory |
| PH-002 | CAP-001 | TRK-002 | EVD-003 | MEDIUM / constraining | data-model | Consider limit Y | optional |
## Sources
- [Source title](URL) -> [why it matters]
## Planning Handoff Readiness Checklist
- [ ] All CAPs have explicit exit status (`proven` / `constrained` / `blocked` / `not-viable`)
- [ ] All PH items trace to evidence (EVD/SPK/repo path)
- [ ] All spike results recorded with pass/fail outcome
- [ ] All residual risks explicitly linked to evidence IDs
- [ ] All research exclusions have revisit conditions
- [ ] `alignment.md` updated with feasibility result and Planning Gate Recommendation
- [ ] `context.md` updated with implementation-chain evidence, constraints, rejected options
- [ ] `references.md` updated with external sources
- [ ] `workflow-state.md` updated with exit criteria and `next_command`
- [ ] Reverse Coverage Validation passed (all CAP→PH→Evidence chains closed)
- [ ] Readiness Refusal Rules all PASS
## Next Command
- [`/sp.plan` | `/sp.clarify` | stop with blocker]
- Update upstream artifacts when research changes planning readiness:
- Update
alignment.md:- add feasibility result, capability status, implementation-chain confidence, Planning Handoff readiness, and Planning Gate Recommendation
- recommend
/sp.deep-researchonly when more feasibility work remains - recommend
/sp.planonly when every planning-critical capability is proven, constrained enough, not needed, or explicitly force-accepted
- Update
context.md:- add implementation-chain evidence, Planning Handoff summary, spike paths, external constraints, rejected options, and residual risks that
/sp.planmust preserve
- add implementation-chain evidence, Planning Handoff summary, spike paths, external constraints, rejected options, and residual risks that
- Update
references.md:- add external sources and reusable insights
- Run an artifact review gate:
- Review
deep-research.md,alignment.md, andcontext.mdfor:- unproven capability chains presented as facts
- demos with no pass condition
- source claims without source attribution
- subagent findings copied without coordinator synthesis
- missing or vague research orchestration strategy when multiple tracks were available
- missing
Planning Handoffdecisions for capabilities that affect plan structure - production-code edits from the research phase
- feasibility risks not reflected in the Planning Gate Recommendation
- If issues remain, revise the artifacts before handoff.
- Review
12b. Run reverse coverage validation:
- Prove every CAP has at least one PH-ID.
- Prove every PH-ID traces back to at least one evidence item (EVD-###, SPK-###, or live repository path).
- Prove every proven CAP has no remaining unresolved unknown links.
- Prove every blocked CAP has a concrete block reason and next action.
- Prove every accepted evidence packet was consumed by at least one PH or explicitly deferred.
- If any check fails, refuse handoff and write gaps back to workflow-state.md.
```markdown
## Reverse Coverage Validation
| CAP ID | Has PH? | PH IDs | Has Evidence? | Evidence IDs | Proven / Clean? |
|--------|---------|--------|---------------|-------------|-----------------|
| CAP-001 | PASS | PH-001, PH-002 | PASS | EVD-001, SPK-001 | PASS |
| CAP-002 | FAIL | — | — | — | FAIL: No PH assigned |
**Decision**: [PASS / FAIL — if FAIL, refuse handoff]
```
-
Write or update
WORKFLOW_STATE_FILE:- Record:
active_command: sp-deep-researchphase_mode: research-only- current authoritative files
- exit criteria for feasibility completion
- next action required before handoff
next_commandas/sp.plan,/sp.clarify, or/sp.deep-research
- Record:
-
Report completion:
- branch or feature directory
- deep-research artifact path
- spike paths and command results, if any
- research tracks and subagent evidence packet summary, if any
- proven capabilities
- constrained or blocked capabilities
- Planning Handoff summary for
/sp.plan - updated alignment/context/reference paths
- recommended next command
- whether the feature is ready for
/sp.plan - [AGENT] before final completion text, if auto-capture did not preserve a reusable
workflow_gap,project_constraint, ordecision_debt, use the manuallearning capturehelper surface. Required options:--command,--type,--summary,--evidence - Use the user's current language for explanatory text while preserving literal command names, file paths, and fixed status values exactly as written.
Readiness Refusal Rules
Before writing final deep-research.md and recommending /sp.plan, run every
check below. If any check fails, refuse handoff, produce a gap report, and
set next_command to /sp.clarify or mark the phase as blocked.
- [ ] Every CAP has at least one PH-ID assigned
- [ ] Every PH-ID traces to at least one evidence ID (
EVD-###,SPK-###, or live repository path) - [ ] No CAP remains
blockedwithout an explicit user force-accept recorded inalignment.md - [ ] No
provenCAP still has unresolved unknown links in its implementation chain - [ ] Every dispatched subagent returned an accepted evidence packet; rejected packets were retried or escalated
- [ ]
dispatch_shape: subagent-blockedis recorded with a concrete block reason and escalation path - [ ] Every spike with a defined hypothesis was run and has a captured pass/fail result
When refusal happens, output a gap report inline before the refusal decision:
## Readiness Refusal Report
| Check | Status | Affected IDs | Missing / Reason |
|-------|--------|-------------|-------------------|
| All CAPs have PH | FAIL | CAP-003 | No PH assigned |
| All PHs trace to evidence | FAIL | PH-005 | No EVD/SPK/repo path |
| ... | PASS | — | — |
**Decision**: Handoff refused. Next command: `/sp.clarify`
Rules
- Use this command to produce research evidence and a planning handoff, not to design the full architecture.
- Prefer a small, runnable proof over broad speculative prose when the question is "can this work?"
- Disposable demos, research spikes, and proof artifacts validate feasibility for the user's intended capability. They are not a replacement product scope and must not be reframed as the delivered product unless the user explicitly confirms that reduced scope.
- Do not require this command for existing capability tweaks where the repository already shows the path.
- Do not advance to
/sp.planwhen a required capability is stillblockedornot viableunless the user explicitly accepts a redesign or force-proceed risk. - Keep all prototype work isolated under
FEATURE_DIR/research-spikes/. - Do not edit source code, tests, migrations, or production config from this command.
- Do not hand off to
/sp.planwith only raw research notes; synthesize findings intoPlanning Handoff, constraints, rejected options, and residual risks. - If this workflow makes actual source/runtime/template/config/test/generated-asset changes in the current run, follow the shared inline closeout contract:
Inline Project Cognition Update
Workflow-owned mutation closeout is not an external map-maintenance handoff and is not external map maintenance. It is the workflow-local form of /sp-map-update. If this workflow changed project-related source, runtime, templates, generated assets, config, tests, state contracts, shared surfaces, or behavior-bearing docs, closeout MUST run inline project cognition update for the workflow-owned changed paths and affected surfaces before claiming clean completion.
Call the planner first:
project-cognition closeout-plan --workflow "$ACTIVE_WORKFLOW" --format json
When DELTA_SESSION_ID exists, pass it into the planner:
project-cognition closeout-plan --workflow "$ACTIVE_WORKFLOW" --delta-session "$DELTA_SESSION_ID" --format json
Consume workflow_canonical, update_mode, payload_draft, required_agent_fields, unknown_paths, unknown_path_dispositions, delta_append_draft, display-only delta_append_command, update_argv, display-only update_command, and recommended_next_command.
Before running update, fill the fields listed in required_agent_fields from live evidence from this workflow. Supported agent-owned evidence fields include:
verificationbehavior_surfacesgenerated_surfacesstate_contractsknown_unknownsconfidence_notesuser_decisionsboundary
If a field appears in required_agent_fields, provide live-evidence-backed content for it. Fields not listed by required_agent_fields, such as known_unknowns and boundary, are populated only when live evidence supports them; do not invent them to satisfy the shape.
Use known_unknowns only for blockers that make the cognition update unsafe to trust. If the working tree contains unrelated dirty/untracked paths and the workflow uses explicit workflow-owned paths, record that as confidence_notes or boundary.initial_dirty_paths, not as a blocking known_unknowns item.
For each unknown_path_dispositions[] item, set agent_disposition to exactly one allowed value:
adoptable: verified new path inside this workflow-owned scope; it may be recorded in changed/scope paths and verified adoptable paths do not become blockingknown_unknowns.review_only: path informed review but is not adopted into changed coverage.ignored: path remains excluded and must not enter payloads, records, route indexes, evidence, aliases, or minimal live reads.blocking_known_unknown: record it as a known unknown and report partial or blocked cognition closeout.
agent_disposition=adoptable is an agent accounting decision, not proof that runtime indexing already succeeded. Runtime adoption still requires a usable active project-cognition DB, at least one passing verification evidence item, and no blocking known_unknowns. After update_argv runs, inspect result_state, adopted_paths, review_paths, minimal_live_reads, and partial_refresh_reasons; do not explain a remaining partial_refresh as "path_index missing" until those fields show which adoption gate failed.
If update_mode=delta_session, complete delta_append_draft.argv_prefix with agent-owned repeatable flags such as --behavior-surface, --generated-surface, --verification, and accepted --known-unknown values from delta_append_draft.argv_placeholders. Then append the delta event and run update_argv. delta_append_command and update_command are display-only placeholders, not execution strings.
If update_mode=payload_file, write the completed payload_draft to the planner's payload_path. Then run update_argv. update_command is a display-only placeholder, not an execution string.
Completed payload drafts preserve the planner-owned changed_paths and scope_paths and add agent-owned evidence fields before recording.
Structured update invalidates related claims and returns their stable IDs in affected_graph_claims. This is separate from update readiness: generic workflow verification and result_state=ready must not re-promote stale or contradicted graph claims. Only when this workflow already has decisive claim-specific bounded live evidence for an exact returned claim ID may it submit semantic reconciliation intent and run:
project-cognition claim-reconcile prepare --input <intent.json> --format json
project-cognition claim-reconcile apply --input <prepared_packet_path> --format json
Provide only reconciliation intent: workflow, stable claim_id, reason, and evidence containing repository-relative source_path, bounded line span, and supporting or contradicting role. Add verification only when it is claim-specific. The runtime owns the contract version, active generation, expected state and revision, UTC observation and expiry, source kind, content hashes, repository snapshot, IDs, and prepared packet path. Do not author or edit those integrity fields; execute the returned apply_argv exactly. If no such evidence exists, leave the claim stale. If reconciliation returns ready, rerun Compass once so later routing consumes the current evidence basis; partial or blocked reconciliation remains withheld and follows recommended_next_action.
For compatibility with worker handoffs and delta packets, the runtime also accepts verification_evidence as an alias for verification and generated_surface_notes as an alias for generated_surfaces. Verification evidence may be an array of objects (command, result, artifact) or an array of command-result strings, but clean closeout still requires passing verification evidence; failed verification cannot produce a clean ready closeout.
Clean closeout keys on result_state, not status=ok, update_id, last_update_id, or freshness alone:
readyorno_op: project cognition closeout may be clean when ordinary verification also passed.partial_refresh: useful update data was written, but the final workflow state must report partial cognition closeout,partial_refresh_reasons, and the returnedminimal_live_reads. Ifpartial_refresh_reasonsincludesmissing_passing_verification_result, repair the payload or delta evidence and rerunupdate_argvbefore final closeout; do not route that tosp-map-update. If verified workflow-owned paths still remain inreview_pathsafter the update, report implementation completion separately from project-cognition maintenance and name/sp-map-updateas follow-up repair.needs_rebuild: report the exact rebuild condition and route to/sp-map-scan, then/sp-map-build.blocked: report the runtime or validation blocker and the exact recovery command.recorded: legacy recorded-only output; treat it as partial or blocked, never as clean completion.
Never run the complete-refresh or clear-dirty helper after result_state=partial_refresh, needs_rebuild, blocked, or legacy recorded; those helpers are only for states that the runtime and validation prove ready.
Dirty fallback command shape: C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty --reason \"<reason>\" --format json.
Use C:\Users\11034\.specify\bin\project-cognition.exe mark-dirty --reason \"workflow-closeout-failed\" --format json only when inline update cannot complete: when the planner or update command is unavailable, cannot record useful update data, cannot identify workflow-owned scope, or cannot be trusted because verification/workflow completion is not trustworthy. Dirty only when inline update cannot complete.
sp-map-update is for manual/external maintenance and follow-up repair. /sp-map-update remains the external/manual workflow for user edits, interrupted workflow repair, explicit map maintenance, and follow-up repair. It is not routine cleanup for changes this workflow just made. If sp-map-update already ran project-cognition update --reason map-update for the same changed paths, do not run a second workflow-finalize closeout update for those paths.
Post-Execution Checks
Check for extension hooks (after deep research):
- Check if
.specify/extensions.ymlexists in the project root. - If it exists, read it and look for entries under the
hooks.after_deep_researchkey. - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally.
- Filter out hooks where
enabledis explicitlyfalse. Treat hooks without anenabledfield as enabled by default. - For each remaining hook, do not attempt to interpret or evaluate hook
conditionexpressions:- If the hook has no
conditionfield, or it is null/empty, treat the hook as executable. - If the hook defines a non-empty
condition, skip the hook and leave condition evaluation to the HookExecutor implementation.
- If the hook has no
- For each executable hook, output the following based on its
optionalflag:- Optional hook (
optional: true):## Extension Hooks **Optional Hook**: {extension} Command: `/{command}` Description: {description} Prompt: {prompt} To execute: `/{command}` - Mandatory hook (
optional: false):## Extension Hooks **Automatic Hook**: {extension} Executing: `/{command}` EXECUTE_COMMAND: {command}
- Optional hook (
- If no hooks are registered or
.specify/extensions.ymldoes not exist, skip silently.
Claude Code Subagent Capability Discovery
- Execution model: preserve the workflow's existing
subagent-mandatory,subagents-first,adaptive, orsubagent-assistedpolicy. - Dispatch shape: preserve the workflow's existing dispatch shape; use
subagent-blockedonly after the discovery step below fails or is unsafe. - Execution surface: prefer
native-subagentswhen the current runtime supports it; usenoneonly after recording the unavailable or unsafe surface. - Native subagent capability discovery: Before recording
subagent-blocked, check the active tool surface for the integration-native subagent or task-dispatch entrypoint and record the exact missing surface if unavailable. - Do not record
subagent-blockeduntil this capability discovery step is complete and the exact unavailable or unsafe surface is recorded. - Native subagent dispatch: Dispatch subagents through the integration's native subagent support using the shared prompt contract.
- Join behavior: Use the integration-native join point, then integrate results back on the leader path.
- Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.
Claude Code Structured Question Preference
- If this command was routed by
sp-autowithauto_default_recommendation: true, evaluate the automatic recommended/default continuation gate before any question path. - When that gate has one safe recommended/default 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.
- If the automatic gate is not safe, write the blocker and self-unblock recommendation before using the normal question path.
- If the runtime's native structured question tool is available for the current turn and the
sp-autoautomatic gate did not resolve the question, you must use it. - Do not render the textual fallback block when the native tool is available.
- Do not self-authorize textual fallback because the question seems simple, short, or easy to phrase manually.
- 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.
- 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/mode lacks a tool, or that a fallback is being used; ask the user-facing question directly when a question is genuinely required.
- Ask only the minimum number of questions required by this workflow's existing contract.
- Keep the user-visible question text in the user's current language and keep option labels short.
- 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.
- If the native tool is unavailable in the current runtime or the tool call fails, ask one concise plain-text question about the missing feasibility or research-track decision, then continue with the existing research workflow.
- In
deep-research, use this preference for:- whether the feasibility question is actually a requirement gap
- minimum research tracks needed before planning
- manual confirmation before force-proceeding with unresolved feasibility risk
- Native tool target:
AskUserQuestion - When this native tool target is listed for the integration and the runtime does not signal otherwise, assume it is available by default in normal interactive sessions.
- Question count: 1-4 questions per call
- Option count: 2-4 options per question
- Required question fields:
question,header,options,multiSelect - Option fields:
label,description,preview (optional) - Use
multiSelect: falseunless the workflow explicitly needs multiple selections. - Use
metadataonly when tracking or analytics context adds value; otherwise keep the call minimal.
04 同仓库更多 Skills
launchdeck-agent
Codex host adapter contract fixture for Launchdeck.
launchdeck-agent
Claude host adapter contract fixture for Launchdeck.
launchdeck-agent
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.
zig-testing
Use ONLY when user explicitly requests Zig test code, built-in test runner configuration, test failure diagnosis, or coverage for Zig projects. Triggers: "write test zig", "zig test", "testing.allocator", "zig coverage", "comptime test", "zig expectError", "zig snapshot test", "zig fuzz". Do NOT activate for: general Zig coding without test context, build.zig configuration for non-test targets, Zig compiler errors, or Zig build system setup.
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.
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