> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode spec show

> Display detailed specification information

## Syntax

```bash theme={null}
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

<Note>
  This command is useful for understanding a spec's full context, including all entities connected to it through relationships and feedback.
</Note>

## Arguments

<ParamField path="spec-id" type="string" required>
  The ID of the spec to display

  **Example:** `SPEC-001`

  The spec ID must exist in your project.
</ParamField>

## 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:

```bash theme={null}
sudocode spec show SPEC-001
```

<Accordion title="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...
  ```
</Accordion>

### Spec with Parent Hierarchy

View a child spec:

```bash theme={null}
sudocode spec show SPEC-003
```

<Accordion title="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)
  ```
</Accordion>

### Spec with No Relationships

View a standalone spec:

```bash theme={null}
sudocode spec show SPEC-010
```

<Accordion title="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...
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json spec show SPEC-001
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</Accordion>

## 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

<Steps>
  <Step title="View the spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Check implementation status">
    Look at incoming relationships to see which issues implement it
  </Step>

  <Step title="Review feedback">
    Check if there are any unresolved questions or requests
  </Step>

  <Step title="Identify dependencies">
    Review outgoing relationships for specs that need to be read first
  </Step>
</Steps>

### Understanding Spec Context

<Steps>
  <Step title="Find the spec">
    ```bash theme={null}
    sudocode spec list --grep "authentication"
    ```
  </Step>

  <Step title="View details">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Follow references">
    ```bash theme={null}
    sudocode spec show SPEC-010  # From outgoing relationships
    ```
  </Step>

  <Step title="Check implementation">
    ```bash theme={null}
    sudocode issue show ISSUE-001  # From incoming relationships
    ```
  </Step>
</Steps>

### Verifying Spec Updates

<Steps>
  <Step title="Update the spec">
    ```bash theme={null}
    sudocode spec update SPEC-001 --priority 0
    ```
  </Step>

  <Step title="Verify changes">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Check impact">
    Review incoming relationships to see affected issues
  </Step>
</Steps>

## Common Questions

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="How do I see the markdown file content?">
    The `spec show` command displays the content directly in the terminal. To edit the markdown file:

    ```bash theme={null}
    # Get file path from show output
    sudocode spec show SPEC-001
    # Then open in your editor
    vim .sudocode/specs/authentication-system.md
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I hide certain sections?">
    Currently, `spec show` displays all available information. For scripting, use `--json` and parse specific fields with `jq`:

    ```bash theme={null}
    # Get only relationships
    sudocode --json spec show SPEC-001 | jq '.relationships'

    # Get only feedback
    sudocode --json spec show SPEC-001 | jq '.feedback'
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Spec not found">
    **Cause:** The spec ID doesn't exist

    **Solution:**
    Verify the ID with:

    ```bash theme={null}
    sudocode spec list
    ```

    Or search for the spec:

    ```bash theme={null}
    sudocode spec list --grep "authentication"
    ```
  </Accordion>

  <Accordion title="Content section is empty">
    **Cause:** The spec has no description/content in the markdown file

    **Solution:**
    This is normal for newly created specs. Add content by editing the markdown file or using:

    ```bash theme={null}
    sudocode spec update SPEC-001 --description "Your content here"
    ```
  </Accordion>

  <Accordion title="No relationships shown">
    **Cause:** The spec has no relationships created yet

    **Solution:**
    This is normal. Create relationships with:

    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="spec list" icon="list" href="/cli/spec-list">
    List all specs
  </Card>

  <Card title="spec update" icon="pen-to-square" href="/cli/spec-update">
    Update spec properties
  </Card>

  <Card title="spec create" icon="plus" href="/cli/spec-create">
    Create new spec
  </Card>

  <Card title="issue show" icon="eye" href="/cli/issue-show">
    View issue details
  </Card>

  <Card title="link" icon="link" href="/cli/link">
    Create relationships
  </Card>

  <Card title="feedback add" icon="comment-plus" href="/cli/feedback-add">
    Add feedback to spec
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="View a spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Follow relationships">
    Use IDs from the relationships section to explore connected entities
  </Step>

  <Step title="Review feedback">
    Address any open feedback or requests
  </Step>

  <Step title="Create implementation issues">
    ```bash theme={null}
    sudocode issue create "Implement feature"
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>
</Steps>

<Card title="Specs Concept Guide" icon="book" href="/concepts/specs">
  Learn more about specs and how they fit into sudocode's workflow
</Card>