sp-explain
Use when the user needs the current stage artifact, project cognition state, or compatibility/export atlas artifact explained in plain language without changing the underlying files.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sp-explain
- metadata
- { "author": "github-spec-kit", "source": "templates/commands/explain.md" }
- description
- Use when the user needs the current stage artifact, project cognition state, or compatibility/export atlas artifact explained in plain language without changing the underlying files.
- compatibility
- Requires spec-kit project structure with .specify/ directory
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 user needs to understand the current planning-stage artifact, project cognition state, or compatibility/export atlas view before deciding whether to continue, revise, or proceed.
- Primary objective: Translate the current artifact into plain language while staying faithful to what is actually on disk.
- Primary outputs: A structured explanation only; do not rewrite stage artifacts or atlas documents unless another command explicitly requests it.
- Default handoff: $sp-plan or /sp-tasks only after the user is satisfied with the current understanding and wants to advance.
- 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.
For a feature runtime blocker, do not invent resume_argv or overwrite an
existing blocker. The CLI returns a read-only show_argv and structured
resolution_action; next_argv stays empty while evidence is missing. After
the criteria are proven, attach sanitized evidence using the action's declared
input and execute its base argv. It restores the same owner and keeps the full
blocker audit.
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Objective
Explain the current stage artifact in plain language so the user can understand what the system believes, what is settled, what remains open, and what the next stage would do.
Context
- Primary inputs: the most relevant current stage artifact plus any immediately supporting artifacts needed to explain it accurately.
- This command is explanation-only. It does not invent state that is absent and does not rewrite the underlying files.
- If limited collaboration is used for a supporting cross-check, the final explanation still converges back to one render step.
Process
- Resolve the current stage artifact deterministically.
- Load only the supporting context needed to explain it faithfully.
- Optionally run a bounded cross-check lane when the current artifact genuinely benefits from it.
- Render one final structured explanation in the user's language.
Output Contract
- Produce a stage-aware explanation with status, risk, and next-step framing.
- Keep the explanation grounded in what is actually on disk.
- Be explicit when implementation status or another expected artifact is absent.
Guardrails
- Do not invent missing state.
- Do not rewrite stage artifacts from inside
/sp-explain. - Default to
leader-inline-fallbackonly when no safe supporting subagent cross-check lane can be packetized and dispatched safely.
Project Learning
The CLI is the only agent-facing Learning read surface:
- Run
uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 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@6fbbf08a0b6833bb783ec6b418d567776b197ae4 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.
After minimal live inspection identifies a reused operation or changed entry point, rerun targeted recall with current code, tests, and task/contract evidence, for example uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning list --command '<classic-command-name>' --context 'operation_owner=<owner>' --context 'consumer_owner=<consumer>' --context 'outcome=<result-family>' --format json. Do not derive these facets from archived specifications. An exact operation-owner match may surface a cross-command candidate even when the new consumer differs; treat it as a candidate, expand one show_argv, verify it against live evidence, and do not auto-apply it.
When the entrypoint outcome audit is triggered, persist the live facets as learning_context, the contextual invocation as learning_search_refs, and returned refs as learning_candidate_refs. Record exactly one applied, not_applicable, or deferred item in learning_dispositions for every candidate. Do not silently ignore a candidate: applied Learning traces to requirement/consequence refs, not-applicable needs current evidence, and deferred needs an explicit deferral ref.
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@6fbbf08a0b6833bb783ec6b418d567776b197ae4 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.
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.
Outline
Goal: Read the current stage artifact, project cognition artifact, or explicitly requested compatibility/export atlas artifact and explain it in plain language so the user can understand what the system currently believes, what is decided, what is still open, and what the next phase or next relevant view will do.
-
Run
.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnlyfrom repo root once (--json --paths-only/-Json -PathsOnly) and parse the available feature paths.- If
FEATURE_DIRis not already explicit, preferuvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify lane resolve --command explain --ensure-worktreebefore guessing from branch-only context. - When lane resolution returns a materialized lane worktree, explain artifacts from that isolated worktree context so the explanation stays attached to the active feature lane.
- If
-
Resolve the stage artifact deterministically:
- If the user explicitly names a stage, honor it.
- If the user explicitly asks about project cognition, touched-area state, or brownfield runtime truth, resolve
.specify/project-cognition/status.jsonand the smallest matching query-backed artifact first. - Explain handbook artifacts only when the user explicitly requests the compatibility/export surfaces themselves.
- If the user explicitly asks for a compatibility/export handbook,
PROJECT-HANDBOOK.md,architecture,structure,conventions,integrations,workflows,testing, oroperationsartifact, resolve that artifact directly. - Explain the architecture, cognition, or compatibility/export atlas artifact directly instead of forcing a planning-stage fallback.
- Otherwise prefer the most advanced available artifact in this order:
tasks->FEATURE_DIR/tasks.mdplan->FEATURE_DIR/plan.mdspecify->FEATURE_DIR/spec.md
- Supporting files:
specify: also readFEATURE_DIR/alignment.mdandFEATURE_DIR/references.mdif presentclarify: readFEATURE_DIR/spec.md,FEATURE_DIR/alignment.md, andFEATURE_DIR/references.mdtogether, then explain the enhancement state as an extension of the current spec packageplan: also readFEATURE_DIR/research.md,FEATURE_DIR/data-model.md,FEATURE_DIR/contracts/, andFEATURE_DIR/quickstart.mdwhen presenttasks: also readFEATURE_DIR/plan.mdandFEATURE_DIR/spec.mdwhen needed for explanationimplement: if there is no canonical implementation status artifact, explain that implementation status is unavailable from the current file set and fall back to the most recent planning artifact instead of guessingproject cognition: read.specify/project-cognition/status.jsonplus the smallest matching slice needed to explain ownership, dependencies, lifecycle, change impact, or verification routes accuratelycompatibility/export atlas: read the explicitly requested handbook plus the smallest supporting export files needed to explain ownership, dependencies, lifecycle, change impact, or verification routes accurately
-
Read the resolved artifact and any immediately supporting artifact needed to explain it accurately.
- If present, also read
.specify/memory/constitution.mdso the explanation honors the project constitution and its constraints on the current stage artifact.
- If present, also read
-
Before translating the artifact, assess workload shape and the current agent capability snapshot, then apply the shared policy contract:
choose_subagent_dispatch(command_name="explain", snapshot, workload_shape).- Persist the decision fields exactly:
execution_model: subagent-mandatory,dispatch_shape: one-subagent | parallel-subagents,execution_surface: native-subagents. - If repository inspection, artifact reading beyond already-provided context, or evidence cross-checking is needed, dispatch a bounded subagent lane before final explanation.
- If the artifact is fully provided in the current prompt and no repository inspection is needed, the leader may render the explanation directly because no substantive repository task is being executed.
- If required subagent dispatch is unavailable, record
subagent-blockedand stop with the missing capability or packet requirement instead of treating coordinator-authored substantive work as the ordinary path. - If collaboration is justified, keep
explainlanes limited to:- primary artifact reading
- supporting artifact cross-check
- Required join point:
- before rendering the final explanation
- Report the chosen strategy, reason, any
subagent-blockedcondition, and whether supporting cross-check lanes were used.
- Persist the decision fields exactly:
-
Translate the artifact into plain language:
- what this stage is trying to accomplish
- what has already been decided
- what remains open or risky
- what the next stage will do with this information
- for project cognition and compatibility/export atlas views: explain verified facts, inferred relationships, important unknowns, and the next relevant cognition slice or export view
-
Present the explanation as a structured terminal UI built from open blocks, not a raw dump.
TUI Requirements
The output should use a polished terminal presentation with:
- a stage header
- a status block
- an explanation block
- a risk block
- a next-step block
The explanation must remain stage-aware:
specify: explain the requirement package and what it means in everyday termsplan: explain the implementation approach in plain languagetasks: explain what concrete work is about to happenimplement: explain progress, current scope, and active risksproject cognition: explain ownership, dependencies, lifecycle, change impact, confidence, and the next relevant cognition slice in plain languagecompatibility/export atlas: explain ownership, dependencies, lifecycle, change impact, confidence, and the next relevant export view in plain language
Rules
- Keep the explanation grounded in the actual artifact on disk.
- Use subagent lanes for explanation work that needs repository inspection or artifact cross-checking; leader synthesis is limited to fully supplied prompt context with no substantive repository task.
- If a supporting cross-check lane is used, converge back to one final render step before presenting the explanation.
- Use the user's current language for user-visible output unless literal command names, file paths, or fixed status values must remain unchanged.
- Prefer clarity over jargon.
- Do not invent missing state; if something is absent, say it is absent.
Codex 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, confirm the current runtime exposesspawn_agent,wait_agent, andclose_agent; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first. - Do not record
subagent-blockeduntil this capability discovery step is complete and the exact unavailable or unsafe surface is recorded. - Native subagent dispatch: Dispatch bounded subagents through
spawn_agent. - Join behavior: Rejoin with
wait_agent, integrate, thenclose_agent. - Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.
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