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

# Feedback System

> Anchored feedback from issues to specs for bidirectional learning

## What Is Feedback?

The feedback system enables **bidirectional learning** between implementation and design. As agents work on issues, they can provide anchored feedback back to the specs, bridging the gap between what was planned and what was learned during implementation.

<Note>
  **Key Principle:** Specs aren't static documents - they evolve based on feedback from implementation. Agents discover ambiguities, missing requirements, and new constraints that flow back up to improve the specs.
</Note>

**Feedback** is an anchored comment from an issue to a spec. It allows agents (or humans) 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

Each feedback has:

* **Source issue** - The issue where feedback was discovered
* **Target spec** - The spec receiving feedback
* **Content** - The actual feedback message
* **Type** - comment, suggestion, or request
* **Anchor** - Optional location in the spec (line number or text)

## Feedback vs. Relationships

<CardGroup cols={2}>
  <Card title="Feedback" icon="comments">
    **Provides context to specs**

    * From issue → to spec
    * Adds commentary/questions
    * Can be dismissed
    * Anchored to specific locations
  </Card>

  <Card title="Relationships" icon="diagram-project">
    **Connects entities**

    * Between any entities
    * Structural connections
    * Permanent links
    * Graph-based dependencies
  </Card>
</CardGroup>

Use feedback when you need to **comment on** or **question** a spec. Use relationships when you need to **connect** entities structurally.

## Feedback Types

sudocode supports three types of feedback:

<AccordionGroup>
  <Accordion title="comment - General commentary">
    **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
    ```
  </Accordion>

  <Accordion title="suggestion - Propose improvements">
    **Purpose:** Suggest 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
    ```
  </Accordion>

  <Accordion title="request - Ask for clarification">
    **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
    ```
  </Accordion>
</AccordionGroup>

## Smart Anchoring

Feedback can be **anchored** to specific locations in specs using two methods:

### Line Number Anchoring

Anchor feedback to a specific line number:

```bash theme={null}
sudocode feedback add ISSUE-001 SPEC-001 \
  --content "This section needs clarification" \
  --line 42
```

<Info>
  **Best for:** Precise locations, code-like specs with numbered sections
</Info>

### Text Search Anchoring

Anchor feedback by searching for text:

```bash theme={null}
sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Missing edge case handling" \
  --text "Authentication Flow"
```

sudocode will:

1. Search for the text "Authentication Flow" in the spec
2. Anchor the feedback to that location
3. Store context (surrounding text) for relocating if the spec changes

<Info>
  **Best for:** Section headings, stable text that's unlikely to change
</Info>

### No Anchor (General Feedback)

Feedback doesn't require an anchor - you can provide general feedback on the entire spec:

```bash theme={null}
sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Overall implementation was straightforward" \
  --type comment
```

## Anchor Relocation (Future)

<Warning>
  **Smart anchor relocation is planned but not yet fully implemented.** Currently, anchors are stored but not automatically relocated when specs change. This is a future enhancement.
</Warning>

The planned anchor relocation feature will:

* Track when spec content changes around an anchor
* Attempt to relocate the anchor to the new location
* Use fuzzy matching on surrounding context
* Mark anchors as "stale" if relocation fails
* Provide commands to manually relocate or dismiss stale feedback

## Creating Feedback

### Command Syntax

```bash theme={null}
sudocode feedback add <issue-id> <spec-id> [options]
```

**Required arguments:**

* `<issue-id>` - The issue providing feedback
* `<spec-id>` - The spec receiving feedback

**Options:**

* `--content <text>` - Feedback content (required)
* `--type <type>` - Feedback type: comment, suggestion, request (default: comment)
* `--line <number>` - Anchor to line number
* `--text <search>` - Anchor by searching for text

### Examples

<CodeGroup>
  ```bash Comment theme={null}
  sudocode feedback add ISSUE-005 SPEC-001 \
    --type comment \
    --content "Implemented OAuth flow successfully"
  ```

  ```bash Suggestion theme={null}
  sudocode feedback add ISSUE-010 SPEC-002 \
    --type suggestion \
    --content "Consider adding rate limiting to prevent abuse" \
    --line 78
  ```

  ```bash Request theme={null}
  sudocode feedback add ISSUE-015 SPEC-001 \
    --type request \
    --content "Need clarification on session timeout behavior" \
    --text "Session Management"
  ```
</CodeGroup>

## Viewing Feedback

### On Specs

When you view a spec, you'll see all feedback it has received:

```bash theme={null}
sudocode spec show SPEC-001
```

<Accordion title="Example output">
  ```
  SPEC-001: Authentication System
  ================================

  Status: approved
  Priority: 0
  Created: 2025-10-29

  [Spec content...]

  Feedback Received (3):

  FB-001 [request] from ISSUE-015 @ line 42
    "Token expiration policy not specified"
    Status: open
    Created: 2025-10-29 09:00

  FB-002 [suggestion] from ISSUE-010 @ "Session Management"
    "Consider using Redis for session storage"
    Status: open
    Created: 2025-10-29 10:15

  FB-003 [comment] from ISSUE-005
    "OAuth implementation complete"
    Status: open
    Created: 2025-10-29 11:30
  ```
</Accordion>

### On Issues

Issues also show what feedback they've provided:

```bash theme={null}
sudocode issue show ISSUE-015
```

<Accordion title="Example output">
  ```
  ISSUE-015: Implement session timeout
  =====================================

  Status: in_progress
  Priority: 1

  [Issue content...]

  Feedback Provided:
    - FB-001 to SPEC-001: "Token expiration policy not specified"
  ```
</Accordion>

## Agent Workflows

### When Agents Should Provide Feedback

<Steps>
  <Step title="Discovered ambiguity">
    Spec doesn't clearly specify something needed for implementation
  </Step>

  <Step title="Found missing requirement">
    Edge case or scenario not covered in spec
  </Step>

  <Step title="Learned something valuable">
    Implementation revealed a better approach or important constraint
  </Step>

  <Step title="Made assumption">
    Had to assume something to proceed - document it for review
  </Step>

  <Step title="Completed work">
    Successfully implemented - confirm requirements were clear (optional)
  </Step>
</Steps>

### Example Agent Flow

```
Agent working on ISSUE-042:

1. Read SPEC-001 for requirements
2. Start implementing authentication endpoint
3. Discover: "Token expiration not specified in spec"
4. Provide feedback:
   sudocode feedback add ISSUE-042 SPEC-001 \
     --type request \
     --content "Need token expiration policy specified" \
     --line 42
5. Make reasonable assumption (1-hour expiration)
6. Continue implementation
7. Complete issue
```

## Managing Feedback

### Dismissing Feedback

Mark feedback as addressed or not relevant:

```bash theme={null}
sudocode feedback dismiss FB-001 --comment "Updated spec section 3.2"
```

<Info>
  Dismissed feedback is retained but marked as resolved
</Info>

### Listing Feedback

```bash theme={null}
# List all feedback for a spec
sudocode feedback list --spec SPEC-001

# List open feedback across all specs
sudocode feedback list --status open

# List feedback from a specific issue
sudocode feedback list --issue ISSUE-015
```

## Database Schema

For reference, here's how feedback is stored:

```sql theme={null}
CREATE TABLE issue_feedback (
    id TEXT PRIMARY KEY,                    -- Feedback ID
    issue_id TEXT NOT NULL,                 -- Source issue
    spec_id TEXT NOT NULL,                  -- Target spec
    feedback_type TEXT NOT NULL,            -- 'comment' | 'suggestion' | 'request'
    content TEXT NOT NULL,                  -- Feedback content
    agent TEXT,                             -- Optional agent identifier
    anchor TEXT,                            -- Optional JSON anchor data
    dismissed INTEGER NOT NULL DEFAULT 0,   -- 0 = open, 1 = dismissed
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    FOREIGN KEY (issue_id) REFERENCES issues(id),
    FOREIGN KEY (spec_id) REFERENCES specs(id)
);
```

The `anchor` field stores JSON with location information:

```json theme={null}
{
  "line_number": 42,
  "section_heading": "Authentication Flow",
  "text_snippet": "Token expiration policy",
  "context_before": "...",
  "context_after": "..."
}
```

## Best Practices

### Writing Effective Feedback

<AccordionGroup>
  <Accordion title="✅ Good feedback">
    **Clear and specific:**

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

    **Actionable:**

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

    **Contextual:**

    ```
    "While implementing OAuth flow, discovered that refresh token
    expiration isn't defined. Assumed 30 days based on RFC 6749."
    ```
  </Accordion>

  <Accordion title="❌ Avoid these patterns">
    **Too vague:**

    ```
    "This section is unclear"  ❌
    ```

    **No context:**

    ```
    "Fix this"  ❌
    ```

    **Redundant:**

    ```
    "I implemented this"  ❌ (unless providing valuable context)
    ```
  </Accordion>
</AccordionGroup>

### When to Use Each Feedback Type

| Situation             | Type         | Example                            |
| --------------------- | ------------ | ---------------------------------- |
| Need clarification    | `request`    | "What should timeout value be?"    |
| Found better approach | `suggestion` | "Consider using Redis instead"     |
| Document decision     | `comment`    | "Used 1hr expiration based on RFC" |
| Point out gap         | `request`    | "Edge case X not specified"        |
| Share learning        | `comment`    | "Implementation revealed..."       |
| Propose improvement   | `suggestion` | "Add validation for..."            |

### Anchoring Best Practices

<Steps>
  <Step title="Use line numbers for precise locations">
    When you need exact positioning, especially in code-like specs
  </Step>

  <Step title="Use text search for sections">
    Anchor to section headings that are less likely to change
  </Step>

  <Step title="Skip anchor for general feedback">
    If feedback applies to entire spec, don't anchor it
  </Step>

  <Step title="Keep anchors stable">
    Try to anchor to stable text (headings, not prose)
  </Step>
</Steps>

## CLI Commands

Quick reference for feedback commands:

```bash theme={null}
# Add feedback
sudocode feedback add <issue-id> <spec-id> \
  --content "..." \
  [--type comment|suggestion|request] \
  [--line <number>] \
  [--text <search>]

# List feedback
sudocode feedback list [--spec <id>] [--issue <id>] [--status open]

# Show feedback details
sudocode feedback show <feedback-id>

# Dismiss feedback
sudocode feedback dismiss <feedback-id> [--comment "reason"]
```

<Card title="Feedback Command Reference" icon="terminal" href="/cli/feedback-add">
  See complete documentation for all feedback commands
</Card>

## Common Workflows

### Agent Discovers Ambiguity

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

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

### Human Reviews Feedback

<Steps>
  <Step title="Check for open feedback">
    ```bash theme={null}
    sudocode feedback list --status open
    ```
  </Step>

  <Step title="Review specific feedback">
    ```bash theme={null}
    sudocode feedback show FB-001
    ```
  </Step>

  <Step title="Update spec if needed">
    Edit the spec to address the feedback
  </Step>

  <Step title="Dismiss feedback">
    ```bash theme={null}
    sudocode feedback dismiss FB-001 \
      --comment "Updated spec section 3.2 with token policy"
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines" href="/concepts/specs">
    Learn about specs - the documents that receive feedback
  </Card>

  <Card title="Issues" icon="list-check" href="/concepts/issues">
    Learn about issues - the source of implementation feedback
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/spec-driven-development">
    See feedback in action in spec-driven development
  </Card>

  <Card title="Feedback Commands" icon="terminal" href="/cli/feedback-add">
    Complete CLI reference for feedback commands
  </Card>
</CardGroup>