sudocode spec show

Syntax

sudocode spec show <spec-id>

Description

The spec show command displays comprehensive information about a specification. This includes:

Basic metadata (title, priority, timestamps)
File path location
Full content/description
Parent-child relationships
Outgoing relationships (what this spec references/depends on)
Incoming relationships (what references/depends on this spec)
Tags
Feedback received from issues

This command is useful for understanding a spec’s full context, including all entities connected to it through relationships and feedback.

Arguments

spec-id

string

required

The ID of the spec to displayExample: SPEC-001The spec ID must exist in your project.

Output Format

The command displays information in the following sections:

Header Section

Spec ID and Title - Displayed prominently
Priority - 0-4 priority level
File Path - Location of markdown file
Parent - Parent spec ID (if hierarchical)
Created/Updated - Timestamps
Tags - Associated tags

Content Section

Full markdown content of the spec

Outgoing Relationships

Relationships from this spec to other entities
Format: relationship_type → TARGET_ID (entity_type)

Incoming Relationships

Relationships from other entities to this spec
Format: SOURCE_ID (entity_type) → relationship_type

Feedback Received

Feedback provided by issues
Shows feedback ID, source issue, type, status, and preview

Examples

Basic Usage

Display a spec:

sudocode spec show SPEC-001

Expected output

SPEC-001 Authentication System Design
────────────────────────────────────────────────────────────
Priority: 1
File: specs/authentication-system.md
Created: 2025-10-29T10:00:00Z
Updated: 2025-10-29T15:30:00Z
Tags: auth, security, backend

Content:
# Authentication System Design

This spec defines the authentication system for our application.

## Requirements

1. Support OAuth 2.0 for third-party login
2. Implement multi-factor authentication
3. Session management with JWT tokens

Outgoing Relationships:
  references → SPEC-010 (spec)

Incoming Relationships:
  ISSUE-001 (issue) → implements
  ISSUE-002 (issue) → implements
  ISSUE-003 (issue) → implements

Feedback Received:
  FB-001 ← ISSUE-001 [active] [valid]
    Type: request | Authentication Flow (line 42)
    Token expiration policy not specified. Need clarification...

Spec with Parent Hierarchy

View a child spec:

sudocode spec show SPEC-003

Expected output

SPEC-003 Session Management
────────────────────────────────────────────────────────────
Priority: 2
File: specs/session-management.md
Parent: SPEC-001
Created: 2025-10-29T11:00:00Z
Updated: 2025-10-29T16:00:00Z

Content:
Design for session management using JWT tokens...

Outgoing Relationships:
  references → SPEC-001 (spec)

Spec with No Relationships

View a standalone spec:

sudocode spec show SPEC-010

Expected output

SPEC-010 API Design Patterns
────────────────────────────────────────────────────────────
Priority: 2
File: specs/api-design-patterns.md
Created: 2025-10-29T12:00:00Z
Updated: 2025-10-29T12:00:00Z
Tags: api, architecture, patterns

Content:
General API design patterns and best practices...

JSON Output

Get machine-readable output:

sudocode --json spec show SPEC-001

JSON output

{
  "id": "SPEC-001",
  "title": "Authentication System Design",
  "priority": 1,
  "file_path": "specs/authentication-system.md",
  "content": "# Authentication System Design\n\nThis spec defines...",
  "parent_id": null,
  "created_at": "2025-10-29T10:00:00Z",
  "updated_at": "2025-10-29T15:30:00Z",
  "archived": false,
  "relationships": {
    "outgoing": [
      {
        "from_id": "SPEC-001",
        "from_type": "spec",
        "to_id": "SPEC-010",
        "to_type": "spec",
        "relationship_type": "references",
        "created_at": "2025-10-29T10:30:00Z"
      }
    ],
    "incoming": [
      {
        "from_id": "ISSUE-001",
        "from_type": "issue",
        "to_id": "SPEC-001",
        "to_type": "spec",
        "relationship_type": "implements",
        "created_at": "2025-10-29T11:00:00Z"
      }
    ]
  },
  "tags": ["auth", "security", "backend"],
  "feedback": [
    {
      "id": "FB-001",
      "issue_id": "ISSUE-001",
      "spec_id": "SPEC-001",
      "feedback_type": "request",
      "content": "Token expiration policy not specified...",
      "dismissed": false,
      "anchor": {
        "line_number": 42,
        "anchor_status": "valid"
      }
    }
  ]
}

Understanding Relationships

Outgoing Relationships

Shows what this spec connects to:

Outgoing Relationships:
  references → SPEC-010 (spec)
  depends-on → SPEC-005 (spec)

Interpretation: SPEC-001 references SPEC-010 and depends on SPEC-005

Incoming Relationships

Shows what connects to this spec:

Incoming Relationships:
  ISSUE-001 (issue) → implements
  ISSUE-002 (issue) → implements
  SPEC-020 (spec) → references

Interpretation: Two issues implement this spec, and another spec references it

Understanding Feedback

Feedback shows issues providing input on the spec:

Feedback Received:
  FB-001 ← ISSUE-001 [active] [valid]
    Type: request | Authentication Flow (line 42)
    Token expiration policy not specified...

Components:

FB-001 - Feedback ID
ISSUE-001 - Source issue
[active] - Not dismissed
[valid] - Anchor is still valid (line hasn’t moved)
request - Feedback type (comment, suggestion, or request)
line 42 - Anchored location
Preview of feedback content

Common Workflows

Reviewing a Spec Before Work

View the spec

sudocode spec show SPEC-001

Check implementation status

Look at incoming relationships to see which issues implement it

Review feedback

Check if there are any unresolved questions or requests

Identify dependencies

Review outgoing relationships for specs that need to be read first

Understanding Spec Context

Find the spec

sudocode spec list --grep "authentication"

View details

sudocode spec show SPEC-001

Follow references

sudocode spec show SPEC-010  # From outgoing relationships

Check implementation

sudocode issue show ISSUE-001  # From incoming relationships

Verifying Spec Updates

Update the spec

sudocode spec update SPEC-001 --priority 0

Verify changes

sudocode spec show SPEC-001

Check impact

Review incoming relationships to see affected issues

Common Questions

What's the difference between outgoing and incoming relationships?

Outgoing: Relationships FROM this spec TO other entities (what this spec references)
Incoming: Relationships FROM other entities TO this spec (what references this spec)

Example: If SPEC-001 implements requirements from SPEC-010:

SPEC-001 has outgoing references to SPEC-010
SPEC-010 has incoming references from SPEC-001

How do I see the markdown file content?

The spec show command displays the content directly in the terminal. To edit the markdown file:

# Get file path from show output
sudocode spec show SPEC-001
# Then open in your editor
vim .sudocode/specs/authentication-system.md

What does feedback anchor status mean?

Anchor status indicates if feedback is still pointing to the correct location:

[valid] - Anchor is accurate, line hasn’t changed
[relocated] - Content moved, but anchor was successfully relocated
[stale] - Content changed significantly, anchor may be invalid

See the feedback system documentation for details on anchor relocation.

Can I hide certain sections?

Currently, spec show displays all available information. For scripting, use --json and parse specific fields with jq:

# Get only relationships
sudocode --json spec show SPEC-001 | jq '.relationships'

# Get only feedback
sudocode --json spec show SPEC-001 | jq '.feedback'

How do I see specs that reference this spec?

Check the “Incoming Relationships” section. Any spec with a references relationship type is referencing this spec:

Incoming Relationships:
  SPEC-020 (spec) → references

Troubleshooting

Error: Spec not found

Cause: The spec ID doesn’t existSolution: Verify the ID with:

sudocode spec list

Or search for the spec:

sudocode spec list --grep "authentication"

Content section is empty

Cause: The spec has no description/content in the markdown fileSolution: This is normal for newly created specs. Add content by editing the markdown file or using:

sudocode spec update SPEC-001 --description "Your content here"

No relationships shown

Cause: The spec has no relationships created yetSolution: This is normal. Create relationships with:

sudocode link ISSUE-001 SPEC-001 --type implements

spec list

List all specs

spec update

Update spec properties

spec create

Create new spec

issue show

View issue details

link

Create relationships

feedback add

Add feedback to spec

Next Steps

View a spec

sudocode spec show SPEC-001

Follow relationships

Use IDs from the relationships section to explore connected entities

Review feedback

Address any open feedback or requests

Create implementation issues

sudocode issue create "Implement feature"
sudocode link ISSUE-001 SPEC-001 --type implements

Specs Concept Guide

Learn more about specs and how they fit into sudocode’s workflow

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

sudocode spec show

Syntax

Description

Arguments

Output Format

Header Section

Content Section

Outgoing Relationships

Incoming Relationships

Feedback Received

Examples

Basic Usage

Spec with Parent Hierarchy

Spec with No Relationships

JSON Output

Understanding Relationships

Outgoing Relationships

Incoming Relationships

Understanding Feedback

Common Workflows

Reviewing a Spec Before Work

Understanding Spec Context

Verifying Spec Updates

Common Questions

Troubleshooting

spec list

spec update

spec create

issue show

link

feedback add

Next Steps

Specs Concept Guide

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​Arguments

​Output Format

​Header Section

​Content Section

​Outgoing Relationships

​Incoming Relationships

​Feedback Received

​Examples

​Basic Usage

​Spec with Parent Hierarchy

​Spec with No Relationships

​JSON Output

​Understanding Relationships

​Outgoing Relationships

​Incoming Relationships

​Understanding Feedback

​Common Workflows

​Reviewing a Spec Before Work

​Understanding Spec Context

​Verifying Spec Updates

​Common Questions

​Troubleshooting

​Related Commands

spec list

spec update

spec create

issue show

link

feedback add

​Next Steps

Specs Concept Guide

Syntax

Description

Arguments

Output Format

Header Section

Content Section

Outgoing Relationships

Incoming Relationships

Feedback Received

Examples

Basic Usage

Spec with Parent Hierarchy

Spec with No Relationships

JSON Output

Understanding Relationships

Outgoing Relationships

Incoming Relationships

Understanding Feedback

Common Workflows

Reviewing a Spec Before Work

Understanding Spec Context

Verifying Spec Updates

Common Questions

Troubleshooting

Related Commands

Next Steps