SPEC.md Consultation Skill

Before implementing any feature or making architectural decisions, consult SPEC.md through an isolated Explore agent to understand the authoritative requirements and design principles.

Purpose

This skill provides access to SPEC.md (the source of truth for architecture and requirements) through a dedicated subagent that ONLY reads the specification, never the implementation code. This ensures you receive unbiased, authoritative guidance based on requirements rather than potentially incorrect implementations.

When to Use This Skill

Use this proactively when you:

• Begin implementing any feature (check spec requirements first)
• Design API responses or data structures (verify against spec models)
• Make architectural decisions (consult spec design principles)
• Need to understand design rationale for existing patterns
• Encounter conflicting information (get the ground truth)
• Verify technical requirements or constraints
• Check pagination strategies, error handling patterns, or data processing rules

Do NOT use this when:

• You need to understand current implementation details (read code directly)
• You need to see how something is actually implemented (that's not the spec's job)
• You're just checking a simple constant or configuration value

Workflow

1. Formulate Your Question

Be specific about what you need from the spec:

Good questions:

• "What is the opaque cursor strategy for pagination?"
• "How should log data field truncation work?"
• "What are the design principles for response processing?"
• "What is the standardized ToolResponse model structure?"

Bad questions:

• "How is pagination implemented?" (this asks about code, not spec)
• "Tell me everything about transactions" (too broad)

2. Spawn the Spec Consultant Subagent

Use the Task tool to create an Explore agent with a minimal prompt that directs it to read its detailed instructions:

Task tool parameters:
- subagent_type: "Explore"
- description: "Consult SPEC.md about <specific topic>"
- prompt: "Read your detailed instructions from .claude/skills/consult-spec/agent-instructions.md,
          then answer this question: <your specific question>"

This keeps the main agent context clean while giving the subagent full access to its operating constraints and workflow.

3. Resume for Follow-Up Questions

If you need multiple spec queries during the same implementation task:

• Capture the agentId from the first Task result
• Use resume: <agentId> parameter in subsequent Task calls
• This avoids re-reading SPEC.md and maintains context

4. Use the Answer in Your Work

The subagent will return:

• Specific information from SPEC.md
• Line number references (e.g., "lines 285-305")
• Direct quotes from relevant sections
• Design rationale and principles

Use this authoritative guidance to implement features correctly according to the specification.

Example Usage

Scenario: Main agent is implementing a new feature that requires understanding spec requirements

Main agent thinks: "I need to understand the spec requirements before implementing this."

Main agent invokes Task tool:

subagent_type: "Explore"
description: "Consult SPEC.md about [topic]"
prompt: "Read your detailed instructions from .claude/skills/consult-spec/agent-instructions.md,
        then answer this question: [Your specific question about requirements, architecture, or design principles]"

Subagent responds (abstract pattern):

The [requested concept/requirement] is defined in lines XXX-YYY of SPEC.md.

Key requirements:
- [First key principle or requirement from the spec]
- [Second key principle or requirement from the spec]
- [Third key principle or requirement from the spec]

Direct quote (lines XXX-YYY):
"[Relevant quote from the specification that clarifies the requirement]"

The [data structure/model/pattern] should contain:
- [component_name]: [description of requirement]
- [component_name]: [description of requirement]

Additional context in lines XXX-YYY explains [related concept].

Main agent uses this: Implements the feature correctly according to spec requirements

Important Notes

Subagent Scope Constraint

The Explore subagent is instructed to ONLY read SPEC.md. This is enforced through:

• Explicit instructions in the subagent prompt
• Clear rationale (provide source-of-truth, avoid implementation bias)
• Behavioral instruction to refuse other file requests

If the subagent attempts to read other files, strengthen the prompt wording or report the issue.

Why This Matters

SPEC.md is the authoritative source of truth. Implementation code may contain:

• Bugs or deviations from requirements
• Incomplete features
• Temporary workarounds
• Outdated patterns

By consulting SPEC.md through an isolated subagent, you ensure your implementation decisions are based on requirements, not on potentially incorrect existing code.

When to Read Code Directly

You still need to read implementation code when you're:

• Understanding existing patterns to match coding style
• Debugging specific issues
• Refactoring or modifying existing features
• Learning how a feature is currently implemented

Use SPEC.md consultation for "what should this do?" and code reading for "how is this currently done?"