understanding-specs

Validate hierarchical spec documents and generate structured summaries with ADRs.

1|Updated Jan 6, 2026

Search Tags:#context #adr #prd #hierarchy #specs #ingest #trd

Ready to run

npx skills add https://github.com/simonheimlicher/spx-claude --skill understanding-specs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: understanding-specs
Source: https://github.com/simonheimlicher/spx-claude/tree/main/plugins/specs/skills/understanding-specs
Command: npx skills add https://github.com/simonheimlicher/spx-claude --skill understanding-specs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This skill helps teams ensure complete context for a work item by loading and validating all necessary specification documents from product down to the target, preventing misalignment and rework.

Core Features & Use Cases

Load and read product-wide context, including the project guide and ADRs to establish architectural constraints.
Validate capability, feature, and story documents are present, and handle optional PRD/TRD enrichments with an offer-to-create flow.
Generate a structured context summary that lists loaded documents and ADRs, enabling smooth handoff to implementation.

Quick Start

Use the understanding-specs skill with the full work item path, for example: /understanding-specs capability-10_cli/feature-20_commands/story-30_build

Frequently Asked Questions about understanding-specs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I ingest and validate a full spec hierarchy for a work item?▼

To ingest and validate a spec hierarchy, provide the full work item path. The skill reads required documents across product, capability, feature, and story levels, then generates a structured context summary for implementation.

What happens when required specification documents are missing during context loading?▼

When critical specification files are missing, the context loading process aborts. It provides actionable guidance to help you locate or create the necessary documents before proceeding with the work item.

Can I generate implementation context from existing PRD and TRD documents?▼

Yes, you can generate context from existing PRD and TRD documents. The skill reads these enrichments and offers a creation flow to generate corresponding specifications if they are missing from the hierarchy.

How do I locate a work item within product, capability, and feature specification levels?▼

You locate a work item within specification levels by passing its hierarchical path. The skill traverses product, capability, feature, and story documents to establish the exact location and architectural constraints.

Why do I need to load ADRs when validating specification documents?▼

Loading ADRs is necessary when validating specifications to establish architectural constraints. Reading Architecture Decision Records ensures the generated context summary aligns with existing technical decisions and project guidelines.

Does the spec validation process support hierarchical work item paths?▼

Yes, the spec validation process supports hierarchical work item paths. You provide the full nested path, such as capability/feature/story, to accurately ingest and validate the corresponding specification documents.