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

> List feedback entries with stale anchors that may need relocation

## Syntax

```bash theme={null}
sudocode feedback stale
```

## Description

The `feedback stale` command finds feedback entries whose anchors have become stale due to spec content changes. Stale anchors occur when:

* The spec content at the anchor location changed significantly
* Line numbers shifted due to edits elsewhere in the file
* The anchored section was removed or heavily modified
* The text snippet no longer matches the content

When an anchor becomes stale:

* Its `anchor_status` is set to `"stale"`
* The original location is preserved for reference
* The feedback may no longer point to the correct location
* Manual relocation is recommended

Use this command to:

* Identify feedback that needs attention after spec updates
* Find anchors that may be pointing to wrong locations
* Maintain feedback accuracy as specs evolve
* Perform periodic anchor health checks

<Note>
  Automatic anchor relocation is planned but not yet fully implemented. This command helps identify anchors that need manual relocation.
</Note>

## Examples

### Find Stale Anchors

Check for stale feedback:

```bash theme={null}
sudocode feedback stale
```

<Accordion title="Expected output">
  ```
  Found 2 stale anchor(s):

  FB-004 [stale] ISSUE-015 → SPEC-001
    Original: Error Handling (line 38)
    Snippet: "Error response format"

  FB-007 [stale] ISSUE-022 → SPEC-003
    Original: Data Validation (line 125)
    Snippet: "Input sanitization rules"

  Tip: Use `sg feedback relocate <id> --line <number>` to manually relocate anchors
  ```
</Accordion>

### No Stale Anchors

When all anchors are valid:

```bash theme={null}
sudocode feedback stale
```

<Accordion title="Expected output">
  ```
  ✓ No stale anchors found
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json feedback stale
```

<Accordion title="JSON output">
  ```json theme={null}
  [
    {
      "id": "FB-004",
      "issue_id": "ISSUE-015",
      "spec_id": "SPEC-001",
      "feedback_type": "request",
      "content": "Need clarification on error response format. Should we use RFC 7807 problem details format or custom error structure?",
      "agent": "bob",
      "anchor": {
        "line_number": 45,
        "section_heading": "Error Handling",
        "text_snippet": "Error response format",
        "anchor_status": "stale",
        "original_location": {
          "line_number": 38,
          "section_heading": "Error Handling"
        },
        "context_before": "...",
        "context_after": "..."
      },
      "dismissed": false,
      "created_at": "2025-10-28T14:30:00Z",
      "updated_at": "2025-10-29T09:00:00Z"
    },
    {
      "id": "FB-007",
      "issue_id": "ISSUE-022",
      "spec_id": "SPEC-003",
      "feedback_type": "suggestion",
      "content": "Consider adding stricter validation rules for user input fields",
      "agent": "alice",
      "anchor": {
        "line_number": 130,
        "section_heading": "Data Validation",
        "text_snippet": "Input sanitization rules",
        "anchor_status": "stale",
        "original_location": {
          "line_number": 125,
          "section_heading": "Data Validation"
        },
        "context_before": "...",
        "context_after": "..."
      },
      "dismissed": false,
      "created_at": "2025-10-27T16:45:00Z",
      "updated_at": "2025-10-29T08:30:00Z"
    }
  ]
  ```
</Accordion>

## Understanding Stale Anchors

### What Makes an Anchor Stale?

An anchor becomes stale when:

<Steps>
  <Step title="Content changes">
    The text at the anchor location was modified or deleted
  </Step>

  <Step title="Line shifts">
    Insertions or deletions elsewhere caused line numbers to change
  </Step>

  <Step title="Section removal">
    The section containing the anchor was removed or renamed
  </Step>

  <Step title="Structural changes">
    Major reorganization of the spec affected anchor accuracy
  </Step>
</Steps>

### Anchor Status Lifecycle

<CardGroup cols={3}>
  <Card title="valid" icon="circle-check">
    **Accurate**

    Anchor points to correct location, content matches, no action needed.

    Color: Green
  </Card>

  <Card title="relocated" icon="arrows-up-down">
    **Moved**

    Anchor was manually updated to new location, original preserved.

    Color: Yellow
  </Card>

  <Card title="stale" icon="triangle-exclamation">
    **Outdated**

    Anchor may be inaccurate, manual relocation needed.

    Color: Red
  </Card>
</CardGroup>

### Why Anchors Become Stale

<AccordionGroup>
  <Accordion title="Spec was heavily edited">
    **Scenario:** Major rewrite of authentication section

    **Result:** Feedback anchored to line 42 now points to different content

    **Solution:** Review the feedback context and relocate to correct line
  </Accordion>

  <Accordion title="Content was removed">
    **Scenario:** Feature was descoped, section removed from spec

    **Result:** Anchor points to non-existent content

    **Solution:** Dismiss feedback if no longer relevant, or relocate to related section
  </Accordion>

  <Accordion title="Lines were inserted above">
    **Scenario:** New section added before anchored location

    **Result:** Line numbers shifted down, anchor now points to wrong line

    **Solution:** Calculate new line number and relocate
  </Accordion>

  <Accordion title="Section was reorganized">
    **Scenario:** Spec restructuring moved content to different location

    **Result:** Anchor location is stale, content exists elsewhere

    **Solution:** Find new location and relocate anchor
  </Accordion>
</AccordionGroup>

## Common Workflows

### Periodic Anchor Maintenance

<Steps>
  <Step title="Check for stale anchors">
    ```bash theme={null}
    sudocode feedback stale
    ```
  </Step>

  <Step title="Review each stale feedback">
    ```bash theme={null}
    sudocode feedback show FB-004
    ```
  </Step>

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

    Look for where the content actually is now
  </Step>

  <Step title="Relocate or dismiss">
    ```bash theme={null}
    # If content exists at new location
    sudocode feedback relocate FB-004 --line 50

    # If feedback no longer relevant
    sudocode feedback dismiss FB-004
    ```
  </Step>
</Steps>

### After Major Spec Update

<Steps>
  <Step title="Update spec">
    Make significant changes to specification
  </Step>

  <Step title="Check for stale anchors">
    ```bash theme={null}
    sudocode feedback stale
    ```
  </Step>

  <Step title="Batch relocate">
    For each stale anchor, either relocate or dismiss
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    sudocode feedback stale
    ```

    Should show no stale anchors
  </Step>
</Steps>

### Investigate Stale Feedback

<Steps>
  <Step title="List stale feedback">
    ```bash theme={null}
    sudocode feedback stale
    ```
  </Step>

  <Step title="Show full details">
    ```bash theme={null}
    sudocode feedback show FB-004
    ```

    Note the original location
  </Step>

  <Step title="Check spec at original line">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```

    Look at line 38 (original location) to see what changed
  </Step>

  <Step title="Find correct location">
    Search spec for the snippet or related content
  </Step>

  <Step title="Relocate">
    ```bash theme={null}
    sudocode feedback relocate FB-004 --line 52
    ```
  </Step>
</Steps>

### Scripting Examples

### Count Stale Anchors by Spec

```bash theme={null}
# Count stale anchors per spec
sudocode --json feedback stale | \
  jq -r '.[] | .spec_id' | \
  sort | uniq -c | sort -rn
```

### List Specs with Stale Anchors

```bash theme={null}
# Show which specs have stale feedback
sudocode --json feedback stale | \
  jq -r '.[] | .spec_id' | \
  sort -u
```

### Batch Review

```bash theme={null}
# Review all stale feedback interactively
for fb_id in $(sudocode --json feedback stale | jq -r '.[] | .id'); do
  echo "=== Reviewing $fb_id ==="
  sudocode feedback show "$fb_id"
  echo ""
  echo "Enter new line number (or 'd' to dismiss, 's' to skip):"
  read action

  case "$action" in
    [0-9]*)
      sudocode feedback relocate "$fb_id" --line "$action"
      ;;
    d)
      sudocode feedback dismiss "$fb_id"
      ;;
    s)
      echo "Skipped"
      ;;
  esac
  echo ""
done
```

### Generate Stale Anchor Report

```bash theme={null}
# Create report of stale anchors
echo "Stale Anchor Report - $(date)"
echo "================================"
echo ""

sudocode --json feedback stale | jq -r '.[] |
  "ID: \(.id)
Issue: \(.issue_id)
Spec: \(.spec_id)
Original Line: \(.anchor.original_location.line_number)
Current Line: \(.anchor.line_number)
Section: \(.anchor.section_heading)
Content: \(.content | .[0:80])
---"'
```

## Preventing Stale Anchors

<Steps>
  <Step title="Use text anchoring">
    Anchor to section headings when possible:

    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --text "## Authentication" \
      --content "..."
    ```

    Headings are more stable than line numbers
  </Step>

  <Step title="Anchor to stable content">
    Choose anchor points unlikely to change, like major section titles
  </Step>

  <Step title="Check anchors after edits">
    Run `feedback stale` after significant spec changes
  </Step>

  <Step title="Keep feedback current">
    Dismiss outdated feedback promptly
  </Step>
</Steps>

## Comparison with Other Commands

<CardGroup cols={2}>
  <Card title="feedback stale" icon="triangle-exclamation">
    **Find stale anchors**

    * Shows only stale anchors
    * No filtering options
    * Focused on anchor health
    * Suggests relocation

    ```bash theme={null}
    sudocode feedback stale
    ```
  </Card>

  <Card title="feedback list" icon="list">
    **List all feedback**

    * Shows all feedback (all statuses)
    * Multiple filter options
    * General feedback overview
    * Shows status in brackets

    ```bash theme={null}
    sudocode feedback list
    ```
  </Card>
</CardGroup>

**Use `feedback stale` when:**

* Performing anchor maintenance
* After major spec updates
* Doing periodic health checks

**Use `feedback list` when:**

* Browsing all feedback
* Filtering by spec/issue/type
* General feedback review

## Common Questions

<AccordionGroup>
  <Accordion title="Why are some anchors stale even though content looks correct?">
    Line numbers may have shifted due to edits elsewhere in the file. Even small changes above the anchor can cause line number mismatches.

    Review the anchor and relocate if needed:

    ```bash theme={null}
    sudocode feedback relocate FB-004 --line 42
    ```
  </Accordion>

  <Accordion title="Can stale anchors be automatically relocated?">
    Automatic relocation is planned but not yet fully implemented. Currently, use:

    ```bash theme={null}
    sudocode feedback relocate FB-004 --line <new-line>
    ```
  </Accordion>

  <Accordion title="Should I dismiss or relocate stale feedback?">
    **Relocate** if:

    * Content still exists in spec
    * Feedback is still relevant
    * You know the new location

    **Dismiss** if:

    * Content was removed from spec
    * Feedback is no longer relevant
    * Feature was descoped
  </Accordion>

  <Accordion title="How often should I check for stale anchors?">
    Check after:

    * Major spec updates
    * Spec restructuring
    * Content removal
    * Weekly/monthly maintenance (depends on update frequency)
  </Accordion>

  <Accordion title="Will dismissed feedback show as stale?">
    No, dismissed feedback is filtered out by default. Stale anchors only show active feedback.
  </Accordion>

  <Accordion title="Can I prevent anchors from becoming stale?">
    Not entirely, but you can minimize it by:

    * Using text anchoring for stable sections
    * Anchoring to headings
    * Keeping specs stable
    * Reviewing anchors after edits
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command shows no output">
    **Cause:** Either no stale anchors or command failed

    **Solution:**
    Check if there's any feedback:

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

    If feedback exists but no stale anchors, you'll see:

    ```
    ✓ No stale anchors found
    ```
  </Accordion>

  <Accordion title="Anchor marked as stale but content is identical">
    **Cause:** Line number changed but content is same

    **Solution:**
    Relocate to update the anchor:

    ```bash theme={null}
    sudocode feedback relocate FB-004 --line 42
    ```

    This updates the anchor status to "relocated"
  </Accordion>

  <Accordion title="Too many stale anchors after spec update">
    **Cause:** Major spec reorganization

    **Solution:**
    Use batch relocation script:

    ```bash theme={null}
    sudocode feedback stale | grep "FB-" | cut -d' ' -f1 | while read id; do
      echo "Relocate $id"
      # Manually relocate or dismiss each
    done
    ```
  </Accordion>

  <Accordion title="Original location is missing in output">
    **Cause:** Feedback may not have original\_location data

    **Solution:**
    Check full details:

    ```bash theme={null}
    sudocode feedback show FB-004
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="feedback relocate" icon="arrows-up-down" href="/cli/feedback-relocate">
    Manually relocate stale anchor
  </Card>

  <Card title="feedback list" icon="list" href="/cli/feedback-list">
    List all feedback
  </Card>

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

  <Card title="feedback dismiss" icon="check" href="/cli/feedback-dismiss">
    Dismiss feedback
  </Card>

  <Card title="spec show" icon="file-lines" href="/cli/spec-show">
    View spec content
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Check for stale anchors">
    ```bash theme={null}
    sudocode feedback stale
    ```
  </Step>

  <Step title="Review each one">
    ```bash theme={null}
    sudocode feedback show FB-004
    ```
  </Step>

  <Step title="Find correct location">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Relocate or dismiss">
    ```bash theme={null}
    sudocode feedback relocate FB-004 --line 50
    # or
    sudocode feedback dismiss FB-004
    ```
  </Step>
</Steps>

<Card title="Feedback System Concept Guide" icon="book" href="/concepts/feedback">
  Learn more about the feedback system and anchor management
</Card>