understanding-specs

通读某个故事、功能或能力的所有规范，包括 PRD、TRD 与 ADR。适用于开始实施、检查进度，或在被要求“阅读规范”时使用。

SKILL.md

--- frontmatter

name: understanding-specs
description: Read all specs for a story, feature, or capability including PRDs, TRDs, and ADRs. Use when starting implementation, checking progress, or asked to "read the spec".
allowed-tools: Read, Glob, Grep

<accessing_skill_files> When this skill is invoked, Claude Code provides the base directory in the loading message:

code

Base directory for this skill: {skill_dir}

Use this path to access skill files:

•References: {skill_dir}/references/
•Workflows: {skill_dir}/workflows/

IMPORTANT: Do NOT search the project directory for skill files. </accessing_skill_files>

<essential_principles> COMPLETE CONTEXT OR ABORT. NO EXCEPTIONS.

•Every work item requires its spec file (.capability.md, .feature.md, .story.md)
•Missing spec file = ABORT immediately with clear error
•PRD/TRD are optional enrichment - read if present, offer to create spec from them if spec is missing
•Read order: Product → Capability → Feature → Story (top-down)
•All ADRs at all levels must be read and understood
•This skill runs BEFORE any implementation work begins

</essential_principles>

<objective> Verify and load complete hierarchical context for a work item by reading all specification documents from product level down to the target work item. Fails fast with actionable errors when required documents are missing. Ensures implementation skills have complete context including all constraints (ADRs), requirements (PRD/TRD), and specifications before starting work. </objective>

<quick_start> Invoke with FULL work item path:

bash

# ALWAYS use full path (REQUIRED)
/understanding-specs capability-10_cli/feature-20_commands/story-30_build

🚨 NEVER use bare story/feature numbers - BSP numbers are sibling-unique, not globally unique:

bash

# ❌ WRONG: Ambiguous - which story-30?
/understanding-specs story-30_build

# ✅ CORRECT: Unambiguous full path
/understanding-specs capability-10_cli/feature-20_commands/story-30_build

The skill will:

•Locate the work item in specs/work/
•Read all documents from product level down to target
•Fail immediately if any required document is missing
•Output structured context summary when complete

</quick_start>

<intake> Provide the **FULL work item path** you're working on:

•Full path (REQUIRED): capability-NN_slug/feature-NN_slug/story-NN_slug

🚨 BSP numbers are sibling-unique, not globally unique.

❌ WRONG (Ambiguous)	✅ CORRECT (Unambiguous)
"story-30_build"	"capability-10_cli/feature-20_commands/story-30_build"
"implement feature-20"	"implement capability-10_cli/feature-20_commands"

The skill will locate and verify all documents in the hierarchy. </intake>

<routing> All inputs route to: `workflows/ingest-context.md`

This skill has a single workflow that handles all context ingestion. </routing>

<reference_index> Detailed patterns and error handling:

File	Purpose
`references/abort-protocol.md`	Error messages and remediation guidance
`references/document-types.md`	Required documents at each level

</reference_index>

<workflows_index>

Workflow	Purpose
`workflows/ingest-context.md`	Hierarchical document verification

</workflows_index>

<success_criteria> Context ingestion succeeds when:

</success_criteria>