sudocode feedback stale

Syntax

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

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

Examples

Find Stale Anchors

Check for stale feedback:

sudocode feedback stale

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

No Stale Anchors

When all anchors are valid:

sudocode feedback stale

Expected output

✓ No stale anchors found

JSON Output

Get machine-readable output:

sudocode --json feedback stale

JSON output

[
  {
    "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"
  }
]

Understanding Stale Anchors

What Makes an Anchor Stale?

An anchor becomes stale when:

Content changes

The text at the anchor location was modified or deleted

Line shifts

Insertions or deletions elsewhere caused line numbers to change

Section removal

The section containing the anchor was removed or renamed

Structural changes

Major reorganization of the spec affected anchor accuracy

Anchor Status Lifecycle

valid

AccurateAnchor points to correct location, content matches, no action needed.Color: Green

relocated

MovedAnchor was manually updated to new location, original preserved.Color: Yellow

stale

OutdatedAnchor may be inaccurate, manual relocation needed.Color: Red

Why Anchors Become Stale

Spec was heavily edited

Scenario: Major rewrite of authentication sectionResult: Feedback anchored to line 42 now points to different contentSolution: Review the feedback context and relocate to correct line

Content was removed

Scenario: Feature was descoped, section removed from specResult: Anchor points to non-existent contentSolution: Dismiss feedback if no longer relevant, or relocate to related section

Lines were inserted above

Scenario: New section added before anchored locationResult: Line numbers shifted down, anchor now points to wrong lineSolution: Calculate new line number and relocate

Section was reorganized

Scenario: Spec restructuring moved content to different locationResult: Anchor location is stale, content exists elsewhereSolution: Find new location and relocate anchor

Common Workflows

Periodic Anchor Maintenance

Check for stale anchors

sudocode feedback stale

Review each stale feedback

sudocode feedback show FB-004

View current spec

sudocode spec show SPEC-001

Look for where the content actually is now

Relocate or dismiss

# If content exists at new location
sudocode feedback relocate FB-004 --line 50

# If feedback no longer relevant
sudocode feedback dismiss FB-004

After Major Spec Update

Update spec

Make significant changes to specification

Check for stale anchors

sudocode feedback stale

Batch relocate

For each stale anchor, either relocate or dismiss

Verify

sudocode feedback stale

Should show no stale anchors

Investigate Stale Feedback

List stale feedback

sudocode feedback stale

Show full details

sudocode feedback show FB-004

Note the original location

Check spec at original line

sudocode spec show SPEC-001

Look at line 38 (original location) to see what changed

Find correct location

Search spec for the snippet or related content

Relocate

sudocode feedback relocate FB-004 --line 52

Scripting Examples

Count Stale Anchors by Spec

# Count stale anchors per spec
sudocode --json feedback stale | \
  jq -r '.[] | .spec_id' | \
  sort | uniq -c | sort -rn

List Specs with Stale Anchors

# Show which specs have stale feedback
sudocode --json feedback stale | \
  jq -r '.[] | .spec_id' | \
  sort -u

Batch Review

# 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

# 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

Use text anchoring

Anchor to section headings when possible:

sudocode feedback add ISSUE-001 SPEC-001 \
  --text "## Authentication" \
  --content "..."

Headings are more stable than line numbers

Anchor to stable content

Choose anchor points unlikely to change, like major section titles

Check anchors after edits

Run feedback stale after significant spec changes

Keep feedback current

Dismiss outdated feedback promptly

Comparison with Other Commands

feedback stale

Find stale anchors

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

sudocode feedback stale

feedback list

List all feedback

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

sudocode feedback list

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

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:

sudocode feedback relocate FB-004 --line 42

Can stale anchors be automatically relocated?

Automatic relocation is planned but not yet fully implemented. Currently, use:

sudocode feedback relocate FB-004 --line <new-line>

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

How often should I check for stale anchors?

Check after:

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

Will dismissed feedback show as stale?

No, dismissed feedback is filtered out by default. Stale anchors only show active feedback.

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

Troubleshooting

Command shows no output

Cause: Either no stale anchors or command failedSolution: Check if there’s any feedback:

sudocode feedback list

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

✓ No stale anchors found

Anchor marked as stale but content is identical

Cause: Line number changed but content is sameSolution: Relocate to update the anchor:

sudocode feedback relocate FB-004 --line 42

This updates the anchor status to “relocated”

Too many stale anchors after spec update

Cause: Major spec reorganizationSolution: Use batch relocation script:

sudocode feedback stale | grep "FB-" | cut -d' ' -f1 | while read id; do
  echo "Relocate $id"
  # Manually relocate or dismiss each
done

Original location is missing in output

Cause: Feedback may not have original_location dataSolution: Check full details:

sudocode feedback show FB-004

feedback relocate

Manually relocate stale anchor

feedback list

List all feedback

feedback show

View feedback details

feedback dismiss

Dismiss feedback

spec show

View spec content

Next Steps

Check for stale anchors

sudocode feedback stale

Review each one

sudocode feedback show FB-004

Find correct location

sudocode spec show SPEC-001

Relocate or dismiss

sudocode feedback relocate FB-004 --line 50
# or
sudocode feedback dismiss FB-004

Feedback System Concept Guide

Learn more about the feedback system and anchor management

​Syntax

​Description

​Examples

​Find Stale Anchors

​No Stale Anchors

​JSON Output

​Understanding Stale Anchors

​What Makes an Anchor Stale?

​Anchor Status Lifecycle

valid

relocated

stale

​Why Anchors Become Stale

​Common Workflows

​Periodic Anchor Maintenance

​After Major Spec Update

​Investigate Stale Feedback

​Scripting Examples

​Count Stale Anchors by Spec

​List Specs with Stale Anchors

​Batch Review

​Generate Stale Anchor Report

​Preventing Stale Anchors

​Comparison with Other Commands

feedback stale

feedback list

​Common Questions

​Troubleshooting

​Related Commands

feedback relocate

feedback list

feedback show

feedback dismiss

spec show

​Next Steps

Feedback System Concept Guide

Syntax

Description

Examples

Find Stale Anchors

No Stale Anchors

JSON Output

Understanding Stale Anchors

What Makes an Anchor Stale?

Anchor Status Lifecycle

Why Anchors Become Stale

Common Workflows

Periodic Anchor Maintenance

After Major Spec Update

Investigate Stale Feedback

Scripting Examples

Count Stale Anchors by Spec

List Specs with Stale Anchors

Batch Review

Generate Stale Anchor Report

Preventing Stale Anchors

Comparison with Other Commands

Common Questions

Troubleshooting

Related Commands

Next Steps