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

> Add anchored feedback from an issue to a specification, enabling bidirectional learning between implementation and design

## Syntax

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

<Note>
  Feedback enables bidirectional learning - specs aren't static documents, they evolve based on feedback from implementation.
</Note>

## Arguments

<ParamField path="issue-id" type="string" required>
  The issue providing the feedback

  **Example:** `ISSUE-001`

  This is the source of the feedback - typically the issue where the problem was discovered.
</ParamField>

<ParamField path="spec-id" type="string" required>
  The spec receiving the feedback

  **Example:** `SPEC-001`

  This is the target specification that the feedback comments on.
</ParamField>

## Options

<ParamField path="--content" type="string" required>
  Feedback content

  **Example:** `--content "Token expiration policy not specified"`

  The actual feedback message. Be clear and specific about what needs clarification or improvement.
</ParamField>

<ParamField path="--type" type="string" default="comment">
  Feedback type

  **Example:** `--type request`

  Valid types:

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

  See [Feedback Types](#feedback-types) for detailed explanations.
</ParamField>

<ParamField path="--line" type="number">
  Anchor to specific line number

  **Example:** `--line 42`

  The feedback is anchored to this line in the spec. Use for precise positioning.

  **Note:** You must specify either `--line` or `--text`, but not both.
</ParamField>

<ParamField path="--text" type="string">
  Anchor to text snippet

  **Example:** `--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.
</ParamField>

<ParamField path="--agent" type="string">
  Agent or user providing feedback

  **Example:** `--agent "agent-backend-dev"`

  Defaults to `$USER` environment variable or "cli" if not set.
</ParamField>

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

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

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

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

```bash theme={null}
sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Need clarification on token rotation policy" \
  --type request \
  --line 42
```

<Accordion title="Expected output">
  ```
  ✓ Created feedback FB-001
    Issue: ISSUE-001
    Spec: SPEC-001
    Type: request
    Location: Authentication Flow (line 42)
  ```
</Accordion>

### Feedback with Text Anchor

Anchor feedback to a section heading:

```bash theme={null}
sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Session timeout behavior needs specification" \
  --type request \
  --text "Session Management"
```

<Accordion title="Expected output">
  ```
  ✓ Created feedback FB-002
    Issue: ISSUE-001
    Spec: SPEC-001
    Type: request
    Location: Session Management (line 58)
  ```
</Accordion>

### Comment Type Feedback

Document implementation decision:

```bash theme={null}
sudocode feedback add ISSUE-005 SPEC-001 \
  --content "OAuth flow implemented successfully with PKCE extension" \
  --type comment \
  --line 30
```

<Accordion title="Expected output">
  ```
  ✓ Created feedback FB-003
    Issue: ISSUE-005
    Spec: SPEC-001
    Type: comment
    Location: OAuth 2.0 Flow (line 30)
  ```
</Accordion>

### Suggestion Type Feedback

Propose improvement:

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

<Accordion title="Expected output">
  ```
  ✓ Created feedback FB-004
    Issue: ISSUE-010
    Spec: SPEC-002
    Type: suggestion
    Location: API Endpoints (line 78)
  ```
</Accordion>

### With Agent Identifier

Specify agent providing feedback:

```bash theme={null}
sudocode feedback add ISSUE-015 SPEC-001 \
  --content "Implemented with additional error handling for edge cases" \
  --type comment \
  --line 45 \
  --agent "agent-backend-dev"
```

<Accordion title="Expected output">
  ```
  ✓ Created feedback FB-005
    Issue: ISSUE-015
    Spec: SPEC-001
    Type: comment
    Location: Error Handling (line 45)
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json feedback add ISSUE-001 SPEC-001 \
  --content "Need clarification" \
  --type request \
  --line 42
```

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

## Anchor Types

### Line Number Anchoring

Anchor feedback to a specific line:

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

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

<Warning>
  You must specify either `--line` or `--text`, but not both. Specifying both will result in an error.
</Warning>

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

<Info>
  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.
</Info>

## Common Workflows

### Agent Discovers Ambiguity

<Steps>
  <Step title="Agent starts work">
    ```bash theme={null}
    sudocode issue update ISSUE-042 --status in_progress
    ```
  </Step>

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

  <Step title="Agent finds ambiguity">
    Spec doesn't specify token expiration policy
  </Step>

  <Step title="Agent provides feedback">
    ```bash theme={null}
    sudocode feedback add ISSUE-042 SPEC-001 \
      --type request \
      --content "Token expiration not specified. Recommend adding explicit policy." \
      --line 42
    ```
  </Step>

  <Step title="Agent continues with assumption">
    Documents assumption in issue, continues work
  </Step>
</Steps>

### Documenting Implementation Decisions

<Steps>
  <Step title="Complete implementation">
    Finish coding the feature
  </Step>

  <Step title="Add feedback to spec">
    ```bash theme={null}
    sudocode feedback add ISSUE-005 SPEC-001 \
      --type comment \
      --content "Implemented OAuth with PKCE extension for enhanced security" \
      --text "OAuth 2.0"
    ```
  </Step>

  <Step title="Close issue">
    ```bash theme={null}
    sudocode issue close ISSUE-005
    ```
  </Step>
</Steps>

### Suggesting Spec Improvements

<Steps>
  <Step title="Discover better approach">
    While implementing, find a better solution
  </Step>

  <Step title="Suggest to spec">
    ```bash theme={null}
    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"
    ```
  </Step>

  <Step title="Continue with current approach">
    Or wait for spec update before proceeding
  </Step>
</Steps>

## Writing Effective Feedback

### Good Feedback

**Clear and specific:**

```bash theme={null}
--content "Section 3.2 doesn't specify token rotation policy for concurrent refresh requests. Should we use atomic operations or queue requests?"
```

**Actionable:**

```bash theme={null}
--content "Suggest adding rate limiting: 10 requests/minute per IP"
```

**Contextual:**

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

```bash theme={null}
--content "This section is unclear"  # ❌ Not specific
```

**No context:**

```bash theme={null}
--content "Fix this"  # ❌ No explanation
```

**Redundant:**

```bash theme={null}
--content "I implemented this"  # ❌ Unless providing valuable context
```

## Common Questions

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

  <Accordion title="What happens if the line I anchor to changes?">
    The anchor may become "stale" if the spec is significantly edited. Use:

    ```bash theme={null}
    sudocode feedback stale  # Find stale anchors
    sudocode feedback relocate FB-001 --line 50  # Fix manually
    ```
  </Accordion>

  <Accordion title="Can I add multiple feedbacks to the same line?">
    Yes! Multiple feedbacks can anchor to the same location. Each gets a unique ID.
  </Accordion>

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

  <Accordion title="Can I edit feedback after creating it?">
    There's no `feedback update` command currently. To modify feedback:

    1. Dismiss the old feedback
    2. Create new feedback with updated content
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Either --line or --text must be specified">
    **Cause:** You didn't provide an anchor location

    **Solution:**
    Specify one anchor method:

    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --content "..." \
      --line 42
    ```
  </Accordion>

  <Accordion title="Error: Issue not found">
    **Cause:** The issue ID doesn't exist

    **Solution:**
    Verify the issue exists:

    ```bash theme={null}
    sudocode issue list
    ```
  </Accordion>

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

    **Solution:**
    Verify the spec exists:

    ```bash theme={null}
    sudocode spec list
    ```
  </Accordion>

  <Accordion title="Error: Text not found in spec">
    **Cause:** The search text doesn't exist in the spec content

    **Solution:**

    * Check for exact match (case-sensitive)
    * View spec content:
      ```bash theme={null}
      sudocode spec show SPEC-001
      ```
    * Use different search text or switch to `--line`
  </Accordion>

  <Accordion title="Error: Invalid line number">
    **Cause:** Line number is less than 1 or not a number

    **Solution:**
    Use a valid positive integer:

    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 --content "..." --line 10
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <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 feedback on a spec
  </Card>

  <Card title="issue show" icon="list-check" href="/cli/issue-show">
    View feedback from an issue
  </Card>

  <Card title="feedback stale" icon="triangle-exclamation" href="/cli/feedback-stale">
    Find stale anchors
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Work on an issue">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress
    ```
  </Step>

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

  <Step title="Find ambiguity or make suggestion">
    During implementation, discover unclear requirements
  </Step>

  <Step title="Add feedback">
    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --type request \
      --content "Need clarification on X" \
      --line 42
    ```
  </Step>

  <Step title="Continue work">
    Make reasonable assumption and document it
  </Step>
</Steps>

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