sudocode feedback relocate

Syntax

sudocode feedback relocate <feedback-id> --line <line-number>

Description

The feedback relocate command updates the anchor location of a feedback entry when the original anchor has become stale or inaccurate due to spec changes. When you relocate feedback:

A new anchor is created at the specified line
The original location is preserved in anchor.original_location
Anchor status is set to "relocated"
The updated_at timestamp is updated
Changes are exported to JSONL

Use this command when:

Feedback shows as stale but content still exists in spec
Line numbers shifted due to spec edits
You know the correct new location for the feedback
Anchor needs manual correction

Relocation requires you to specify the correct line number. Review the spec content first to ensure accuracy.

Arguments

string

required

The feedback ID to relocateExample: FB-004The feedback entry whose anchor needs updating.

Options

number

required

New line number for the anchorExample: --line 50Must be a valid positive integer within the spec’s line range.

Examples

Relocate Stale Anchor

Fix a stale anchor by moving it to the correct line:

sudocode feedback relocate FB-004 --line 50

Expected output

✓ Relocated feedback anchor FB-004
  New location: Error Handling (line 50)

Relocate After Spec Edit

After adding content that shifted line numbers:

Check stale anchors

sudocode feedback stale

Shows FB-004 is stale at original line 38

View spec

sudocode spec show SPEC-001

Find that content is now at line 50

Relocate

sudocode feedback relocate FB-004 --line 50

Expected output

✓ Relocated feedback anchor FB-004
  New location: Error Response Format (line 50)

Relocate Multiple Anchors

Fix several stale anchors:

sudocode feedback relocate FB-004 --line 50
sudocode feedback relocate FB-007 --line 130
sudocode feedback relocate FB-012 --line 95

Expected output

✓ Relocated feedback anchor FB-004
  New location: Error Handling (line 50)
✓ Relocated feedback anchor FB-007
  New location: Data Validation (line 130)
✓ Relocated feedback anchor FB-012
  New location: API Design (line 95)

Invalid Line Number

Attempt to relocate to invalid line:

sudocode feedback relocate FB-004 --line 999999

Expected output

✗ Failed to relocate feedback
Invalid line number or line exceeds spec length

Non-Existent Feedback

Attempt to relocate feedback that doesn’t exist:

sudocode feedback relocate FB-999 --line 50

Expected output

✗ Feedback not found: FB-999

JSON Output

Get machine-readable output:

sudocode --json feedback relocate FB-004 --line 50

JSON output

{
  "id": "FB-004",
  "issue_id": "ISSUE-015",
  "spec_id": "SPEC-001",
  "feedback_type": "request",
  "content": "Need clarification on error response format...",
  "agent": "bob",
  "anchor": {
    "line_number": 50,
    "section_heading": "Error Response Format",
    "text_snippet": "Error structure definition",
    "anchor_status": "relocated",
    "original_location": {
      "line_number": 38,
      "section_heading": "Error Handling"
    },
    "context_before": "## Error Response Format\n\nOur API returns errors in a consistent format.",
    "context_after": "All errors include a code and message field.\n\n### Error Codes"
  },
  "dismissed": false,
  "created_at": "2025-10-28T14:30:00Z",
  "updated_at": "2025-10-29T15:20:00Z"
}

Notice:

anchor_status is now "relocated"
original_location preserves the original line 38
New line_number is 50
updated_at timestamp reflects the relocation

What Happens During Relocation

Fetch spec content

The spec content is retrieved from the database

Create new anchor

A new anchor is generated at the specified line, including:

New line number
Updated section heading
New text snippet
Context before/after

Preserve original

Original location is saved in anchor.original_location:

Original line number
Original section heading

Set status

Anchor status is set to "relocated"

Update feedback

The feedback entry is updated in the database with new anchor

Update timestamp

updated_at is set to current time

Export to JSONL

Changes are written to feedback.jsonl

Understanding Relocated Status

After relocation, the feedback anchor has "relocated" status:

valid

Original anchor

Never moved
Content unchanged
No original_location

Color: Green

relocated

Manually updated

Moved to new line
Original preserved
Intentional update

Color: Yellow

stale

Needs attention

Content changed
Location uncertain
Requires relocation

Color: Red

The relocated status indicates:

The anchor was manually updated (not stale detection)
The original location is preserved for audit trail
The feedback is now accurately anchored

Common Workflows

Fix Stale Anchors

Find stale anchors

sudocode feedback stale

Review first stale feedback

sudocode feedback show FB-004

Note the original line and content

View spec

sudocode spec show SPEC-001

Search for the content or section

Identify new line

Determine the correct line number where content now exists

Relocate

sudocode feedback relocate FB-004 --line 50

Verify

sudocode feedback show FB-004

Check that status is “relocated” and location is correct

After Major Spec Update

Update spec

Make significant changes to specification

Check for stale anchors

sudocode feedback stale

Batch relocate

For each stale anchor:

sudocode feedback relocate FB-004 --line 50
sudocode feedback relocate FB-007 --line 130

Verify all fixed

sudocode feedback stale

Should show: ✓ No stale anchors found

Calculate New Line After Insertion

If you inserted 10 lines at line 20:

# Original anchor at line 38
# Lines inserted: 10 at line 20
# New line: 38 + 10 = 48

sudocode feedback relocate FB-004 --line 48

Interactive Relocation

Review and relocate interactively:

for fb_id in $(sudocode --json feedback stale | jq -r '.[] | .id'); do
  echo "=== Relocating $fb_id ==="

  # Show feedback details
  sudocode feedback show "$fb_id"

  # Show spec
  spec_id=$(sudocode --json feedback show "$fb_id" | jq -r '.spec_id')
  echo ""
  echo "Spec content:"
  sudocode spec show "$spec_id" | head -50

  # Ask for new line
  echo ""
  echo "Enter new line number (or 'skip'):"
  read line_num

  if [[ "$line_num" =~ ^[0-9]+$ ]]; then
    sudocode feedback relocate "$fb_id" --line "$line_num"
  else
    echo "Skipped $fb_id"
  fi
  echo ""
done

Scripting Examples

Bulk Relocate with Mapping

If you know the line number changes:

# Map of FB-ID to new line number
declare -A relocations=(
  ["FB-004"]=50
  ["FB-007"]=130
  ["FB-012"]=95
)

for fb_id in "${!relocations[@]}"; do
  line="${relocations[$fb_id]}"
  echo "Relocating $fb_id to line $line"
  sudocode feedback relocate "$fb_id" --line "$line"
done

Calculate Offset Relocation

If all lines shifted by same amount:

# All lines shifted down by 15
offset=15

sudocode --json feedback stale | jq -r '.[] | "\(.id) \(.anchor.line_number)"' | \
while read fb_id old_line; do
  new_line=$((old_line + offset))
  echo "Relocating $fb_id from $old_line to $new_line"
  sudocode feedback relocate "$fb_id" --line "$new_line"
done

Generate Relocation Plan

# Create a plan before executing
echo "Relocation Plan"
echo "==============="

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

echo ""
echo "Review the plan above, then run relocations manually"

Finding the Correct Line

Method 1: Search by Snippet

# Get the snippet from feedback
snippet=$(sudocode --json feedback show FB-004 | jq -r '.anchor.text_snippet')

# Search spec for snippet
sudocode spec show SPEC-001 | grep -n "$snippet"

Method 2: Search by Section

# Get section heading
section=$(sudocode --json feedback show FB-004 | jq -r '.anchor.section_heading')

# Find section in spec
sudocode spec show SPEC-001 | grep -n "## $section"

Method 3: Manual Review

# Show spec with line numbers
sudocode spec show SPEC-001 | nl -v 1

# Visually find the correct line

Common Questions

Can I relocate an already relocated anchor?

Yes, you can relocate feedback multiple times. Each relocation updates the line number but preserves the original location from the first creation.

sudocode feedback relocate FB-004 --line 50  # First relocation
sudocode feedback relocate FB-004 --line 55  # Second relocation

The original_location always refers to the first anchor location.

How do I know what line to relocate to?

Show the feedback to see the snippet:
sudocode feedback show FB-004

Search the spec for that content:

sudocode spec show SPEC-001 | grep -n "snippet text"

Use the line number from grep output

Can I relocate feedback to a different spec?

No, relocation only changes the line number within the same spec. To move feedback to a different spec, you must:

Dismiss the old feedback
Create new feedback on the new spec

What happens to original_location after multiple relocations?

It always preserves the very first location where feedback was created, not intermediate relocations. This maintains the complete history.

Can I relocate valid anchors?

Yes, technically you can relocate any feedback, not just stale ones. But it’s usually only necessary for stale anchors. Relocating a valid anchor would change its status to “relocated”.

Is there a way to undo a relocation?

Not directly. To undo:

# Get original line number
orig_line=$(sudocode --json feedback show FB-004 | jq -r '.anchor.original_location.line_number')

# Relocate back
sudocode feedback relocate FB-004 --line "$orig_line"

However, the status will still show “relocated” not “valid”.

Troubleshooting

Error: Invalid line number

Cause: Line number is less than 1, not a number, or exceeds spec lengthSolution: Check spec length:

sudocode spec show SPEC-001 | wc -l

Ensure line number is within range:

sudocode feedback relocate FB-004 --line 42

Error: Feedback not found

Cause: The feedback ID doesn’t existSolution: List all feedback:

sudocode feedback list

Use correct ID

Error: Spec not found

Cause: The spec referenced by feedback doesn’t existSolution: This shouldn’t happen if feedback exists. Check database integrity:

sudocode sync

Relocation succeeded but anchor still shows as stale

Cause: Content at new line may not match expectedSolution: Verify the new location:

sudocode feedback show FB-004

Status should be “relocated”, not “stale”. If still stale, you may have chosen wrong line.

Can't calculate correct line number after major spec rewrite

Cause: Too many changes to accurately map old to new lineSolution: Consider dismissing old feedback and creating new:

sudocode feedback dismiss FB-004
sudocode feedback add ISSUE-015 SPEC-001 \
  --content "Updated feedback..." \
  --line 50

feedback stale

Find stale anchors

feedback show

View feedback details

feedback dismiss

Dismiss feedback

spec show

View spec content

feedback list

List all feedback

Next Steps

Find stale anchors

sudocode feedback stale

Show feedback details

sudocode feedback show FB-004

View spec

sudocode spec show SPEC-001

Find correct line number

Relocate

sudocode feedback relocate FB-004 --line 50

Verify

sudocode feedback show FB-004

Check status is “relocated”

Feedback System Concept Guide

Learn more about the feedback system and anchor management

​Syntax

​Description

​Arguments

​Options

​Examples

​Relocate Stale Anchor

​Relocate After Spec Edit

​Relocate Multiple Anchors

​Invalid Line Number

​Non-Existent Feedback

​JSON Output

​What Happens During Relocation

​Understanding Relocated Status

valid

relocated

stale

​Common Workflows

​Fix Stale Anchors

​After Major Spec Update

​Calculate New Line After Insertion

​Interactive Relocation

​Scripting Examples

​Bulk Relocate with Mapping

​Calculate Offset Relocation

​Generate Relocation Plan

​Finding the Correct Line

​Method 1: Search by Snippet

​Method 2: Search by Section

​Method 3: Manual Review

​Common Questions

​Troubleshooting

​Related Commands

feedback stale

feedback show

feedback dismiss

spec show

feedback list

​Next Steps

Feedback System Concept Guide

Syntax

Description

Arguments

Options

Examples

Relocate Stale Anchor

Relocate After Spec Edit

Relocate Multiple Anchors

Invalid Line Number

Non-Existent Feedback

JSON Output

What Happens During Relocation

Understanding Relocated Status

Common Workflows

Fix Stale Anchors

After Major Spec Update

Calculate New Line After Insertion

Interactive Relocation

Scripting Examples

Bulk Relocate with Mapping

Calculate Offset Relocation

Generate Relocation Plan

Finding the Correct Line

Method 1: Search by Snippet

Method 2: Search by Section

Method 3: Manual Review

Common Questions

Troubleshooting

Related Commands

Next Steps