sudocode feedback add

Syntax

sudocode feedback add <issue-id> <spec-id> [options]

Description

The feedback add command creates anchored feedback from an issue to a spec. This enables agents and developers to:

Point out ambiguities discovered during implementation
Request clarification on unclear requirements
Suggest improvements based on actual implementation
Document assumptions made when specs were incomplete

Feedback is anchored to specific locations in the spec using line numbers or text search, allowing precise context for comments.

Feedback enables bidirectional learning - specs aren’t static documents, they evolve based on feedback from implementation.

Arguments

issue-id

string

required

The issue providing the feedbackExample: ISSUE-001This is the source of the feedback - typically the issue where the problem was discovered.

spec-id

string

required

The spec receiving the feedbackExample: SPEC-001This is the target specification that the feedback comments on.

Options

--content

string

required

Feedback contentExample: --content "Token expiration policy not specified"The actual feedback message. Be clear and specific about what needs clarification or improvement.

--type

string

default:"comment"

Feedback typeExample: --type requestValid types:

comment - General commentary or information
suggestion - Propose improvements
request - Ask for clarification

See Feedback Types for detailed explanations.

--line

number

Anchor to specific line numberExample: --line 42The feedback is anchored to this line in the spec. Use for precise positioning.Note: You must specify either --line or --text, but not both.

--text

string

Anchor to text snippetExample: --text "Authentication Flow"Searches for this text in the spec and anchors the feedback there. Better for headings or stable text.Note: You must specify either --line or --text, but not both.

--agent

string

Agent or user providing feedbackExample: --agent "agent-backend-dev"Defaults to $USER environment variable or “cli” if not set.

Feedback Types

comment

Purpose: Provide informational feedback without requesting action Use cases:

Document implementation decisions
Explain assumptions made
Share learnings from implementation
Provide status updates

Example:

sudocode feedback add ISSUE-001 SPEC-001 \
  --type comment \
  --content "Implemented using JWT tokens as specified. Added 1-hour expiration." \
  --line 42

suggestion

Purpose: Propose changes or improvements to the spec Use cases:

Propose better approaches discovered during implementation
Suggest additional features
Recommend spec clarifications
Share best practices

Example:

sudocode feedback add ISSUE-002 SPEC-001 \
  --type suggestion \
  --content "Consider using refresh token rotation for better security" \
  --line 55

request

Purpose: Request clarification or additional requirements Use cases:

Point out ambiguities
Ask about missing edge cases
Request technical specifications
Highlight gaps in requirements

Example:

sudocode feedback add ISSUE-003 SPEC-001 \
  --type request \
  --content "Token expiration policy not specified. Should we use fixed or sliding window?" \
  --line 42

Examples

Basic Feedback with Line Anchor

Add feedback anchored to line 42:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Need clarification on token rotation policy" \
  --type request \
  --line 42

Expected output

✓ Created feedback FB-001
  Issue: ISSUE-001
  Spec: SPEC-001
  Type: request
  Location: Authentication Flow (line 42)

Feedback with Text Anchor

Anchor feedback to a section heading:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Session timeout behavior needs specification" \
  --type request \
  --text "Session Management"

Expected output

✓ Created feedback FB-002
  Issue: ISSUE-001
  Spec: SPEC-001
  Type: request
  Location: Session Management (line 58)

Comment Type Feedback

Document implementation decision:

sudocode feedback add ISSUE-005 SPEC-001 \
  --content "OAuth flow implemented successfully with PKCE extension" \
  --type comment \
  --line 30

Expected output

✓ Created feedback FB-003
  Issue: ISSUE-005
  Spec: SPEC-001
  Type: comment
  Location: OAuth 2.0 Flow (line 30)

Suggestion Type Feedback

Propose improvement:

sudocode feedback add ISSUE-010 SPEC-002 \
  --content "Consider adding rate limiting to prevent abuse: 10 requests/minute per client" \
  --type suggestion \
  --text "API Endpoints"

Expected output

✓ Created feedback FB-004
  Issue: ISSUE-010
  Spec: SPEC-002
  Type: suggestion
  Location: API Endpoints (line 78)

With Agent Identifier

Specify agent providing feedback:

sudocode feedback add ISSUE-015 SPEC-001 \
  --content "Implemented with additional error handling for edge cases" \
  --type comment \
  --line 45 \
  --agent "agent-backend-dev"

Expected output

✓ Created feedback FB-005
  Issue: ISSUE-015
  Spec: SPEC-001
  Type: comment
  Location: Error Handling (line 45)

JSON Output

Get machine-readable output:

sudocode --json feedback add ISSUE-001 SPEC-001 \
  --content "Need clarification" \
  --type request \
  --line 42

JSON output

{
  "id": "FB-001",
  "issue_id": "ISSUE-001",
  "spec_id": "SPEC-001",
  "feedback_type": "request",
  "content": "Need clarification",
  "agent": "alice",
  "anchor": {
    "line_number": 42,
    "section_heading": "Authentication Flow",
    "text_snippet": "Token expiration policy",
    "anchor_status": "valid",
    "context_before": "...",
    "context_after": "..."
  },
  "dismissed": false,
  "created_at": "2025-10-29T10:30:00Z",
  "updated_at": "2025-10-29T10:30:00Z"
}

Anchor Types

Line Number Anchoring

Anchor feedback to a specific line:

--line 42

Advantages:

Precise positioning
No ambiguity
Fast execution

Disadvantages:

Line numbers change as content is edited
May become stale if spec is modified

Text Search Anchoring

Anchor feedback by searching for text:

--text "Authentication Flow"

Advantages:

Based on stable content (headings)
More maintainable
Better for section-level feedback

Disadvantages:

Requires exact text match
May fail if text changes
Only anchors to first match

You must specify either --line or --text, but not both. Specifying both will result in an error.

Anchor Status

When feedback is created, the anchor has a status:

valid - Anchor is accurate, line hasn’t changed
relocated - Content moved, anchor was successfully relocated (future feature)
stale - Content changed significantly, anchor may be invalid

Automatic anchor relocation is planned but not yet fully implemented. Use sudocode feedback stale to find stale anchors and sudocode feedback relocate to manually fix them.

Common Workflows

Agent Discovers Ambiguity

Agent starts work

sudocode issue update ISSUE-042 --status in_progress

Agent reads spec

sudocode spec show SPEC-001

Agent finds ambiguity

Spec doesn’t specify token expiration policy

Agent provides feedback

sudocode feedback add ISSUE-042 SPEC-001 \
  --type request \
  --content "Token expiration not specified. Recommend adding explicit policy." \
  --line 42

Agent continues with assumption

Documents assumption in issue, continues work

Documenting Implementation Decisions

Complete implementation

Finish coding the feature

Add feedback to spec

sudocode feedback add ISSUE-005 SPEC-001 \
  --type comment \
  --content "Implemented OAuth with PKCE extension for enhanced security" \
  --text "OAuth 2.0"

Close issue

sudocode issue close ISSUE-005

Suggesting Spec Improvements

Discover better approach

While implementing, find a better solution

Suggest to spec

sudocode feedback add ISSUE-010 SPEC-001 \
  --type suggestion \
  --content "Consider using Redis for session storage instead of in-memory. Better scalability." \
  --text "Session Management"

Continue with current approach

Or wait for spec update before proceeding

Writing Effective Feedback

Good Feedback

Clear and specific:

--content "Section 3.2 doesn't specify token rotation policy for concurrent refresh requests. Should we use atomic operations or queue requests?"

Actionable:

--content "Suggest adding rate limiting: 10 requests/minute per IP"

Contextual:

--content "While implementing OAuth flow, discovered that refresh token expiration isn't defined. Assumed 30 days based on RFC 6749."

Avoid These Patterns

Too vague:

--content "This section is unclear"  # ❌ Not specific

No context:

--content "Fix this"  # ❌ No explanation

Redundant:

--content "I implemented this"  # ❌ Unless providing valuable context

Common Questions

Can I add feedback without an issue?

No, feedback must come from an issue. This maintains traceability - you know which implementation work discovered the problem.If you need to comment on a spec without an issue, create a placeholder issue first.

What happens if the line I anchor to changes?

The anchor may become “stale” if the spec is significantly edited. Use:

sudocode feedback stale  # Find stale anchors
sudocode feedback relocate FB-001 --line 50  # Fix manually

Can I add multiple feedbacks to the same line?

Yes! Multiple feedbacks can anchor to the same location. Each gets a unique ID.

Should I use line or text anchoring?

Use text for:

Section headings (stable)
Important keywords (unlikely to change)

Use line for:

Specific code-like content
When you need exact positioning

Can I edit feedback after creating it?

There’s no feedback update command currently. To modify feedback:

Dismiss the old feedback
Create new feedback with updated content

Troubleshooting

Error: Either --line or --text must be specified

Cause: You didn’t provide an anchor locationSolution: Specify one anchor method:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "..." \
  --line 42

Error: Issue not found

Cause: The issue ID doesn’t existSolution: Verify the issue exists:

sudocode issue list

Error: Spec not found

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

sudocode spec list

Error: Text not found in spec

Cause: The search text doesn’t exist in the spec contentSolution:

Check for exact match (case-sensitive)
View spec content:
sudocode spec show SPEC-001
Use different search text or switch to --line

Error: Invalid line number

Cause: Line number is less than 1 or not a numberSolution: Use a valid positive integer:

sudocode feedback add ISSUE-001 SPEC-001 --content "..." --line 10

feedback list

List all feedback

feedback show

View feedback details

feedback dismiss

Dismiss feedback

spec show

View feedback on a spec

issue show

View feedback from an issue

feedback stale

Find stale anchors

Next Steps

Work on an issue

sudocode issue update ISSUE-001 --status in_progress

Read the spec

sudocode spec show SPEC-001

Find ambiguity or make suggestion

During implementation, discover unclear requirements

Add feedback

sudocode feedback add ISSUE-001 SPEC-001 \
  --type request \
  --content "Need clarification on X" \
  --line 42

Continue work

Make reasonable assumption and document it

Feedback System Concept Guide

Learn more about the feedback system and bidirectional learning

​Syntax

​Description

​Arguments

​Options

​Feedback Types

​comment

​suggestion

​request

​Examples

​Basic Feedback with Line Anchor

​Feedback with Text Anchor

​Comment Type Feedback

​Suggestion Type Feedback

​With Agent Identifier

​JSON Output

​Anchor Types

​Line Number Anchoring

​Text Search Anchoring

​Anchor Status

​Common Workflows

​Agent Discovers Ambiguity

​Documenting Implementation Decisions

​Suggesting Spec Improvements

​Writing Effective Feedback

​Good Feedback

​Avoid These Patterns

​Common Questions

​Troubleshooting

​Related Commands

feedback list

feedback show

feedback dismiss

spec show

issue show

feedback stale

​Next Steps

Feedback System Concept Guide

Syntax

Description

Arguments

Options

Feedback Types

comment

suggestion

request

Examples

Basic Feedback with Line Anchor

Feedback with Text Anchor

Comment Type Feedback

Suggestion Type Feedback

With Agent Identifier

JSON Output

Anchor Types

Line Number Anchoring

Text Search Anchoring

Anchor Status

Common Workflows

Agent Discovers Ambiguity

Documenting Implementation Decisions

Suggesting Spec Improvements

Writing Effective Feedback

Good Feedback

Avoid These Patterns

Common Questions

Troubleshooting

Related Commands

Next Steps