Feedback System - sudocode

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.

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.

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

Feedback

Provides context to specs

From issue → to spec
Adds commentary/questions
Can be dismissed
Anchored to specific locations

Relationships

Connects entities

Between any entities
Structural connections
Permanent links
Graph-based dependencies

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:

comment - General commentary

Purpose: Provide informational feedback without requesting actionUse 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 - Propose improvements

Purpose: Suggest changes or improvements to the specUse 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 - Ask for clarification

Purpose: Request clarification or additional requirementsUse 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

Smart Anchoring

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

Line Number Anchoring

Anchor feedback to a specific line number:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "This section needs clarification" \
  --line 42

Best for: Precise locations, code-like specs with numbered sections

Text Search Anchoring

Anchor feedback by searching for text:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Missing edge case handling" \
  --text "Authentication Flow"

sudocode will:

Search for the text “Authentication Flow” in the spec
Anchor the feedback to that location
Store context (surrounding text) for relocating if the spec changes

Best for: Section headings, stable text that’s unlikely to change

No Anchor (General Feedback)

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

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Overall implementation was straightforward" \
  --type comment

Anchor Relocation (Future)

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.

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

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

sudocode feedback add ISSUE-005 SPEC-001 \
  --type comment \
  --content "Implemented OAuth flow successfully"

sudocode feedback add ISSUE-010 SPEC-002 \
  --type suggestion \
  --content "Consider adding rate limiting to prevent abuse" \
  --line 78

sudocode feedback add ISSUE-015 SPEC-001 \
  --type request \
  --content "Need clarification on session timeout behavior" \
  --text "Session Management"

Viewing Feedback

On Specs

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

sudocode spec show SPEC-001

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

On Issues

Issues also show what feedback they’ve provided:

sudocode issue show ISSUE-015

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"

Agent Workflows

When Agents Should Provide Feedback

Discovered ambiguity

Spec doesn’t clearly specify something needed for implementation

Found missing requirement

Edge case or scenario not covered in spec

Learned something valuable

Implementation revealed a better approach or important constraint

Made assumption

Had to assume something to proceed - document it for review

Completed work

Successfully implemented - confirm requirements were clear (optional)

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:

sudocode feedback dismiss FB-001 --comment "Updated spec section 3.2"

Dismissed feedback is retained but marked as resolved

Listing Feedback

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

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:

{
  "line_number": 42,
  "section_heading": "Authentication Flow",
  "text_snippet": "Token expiration policy",
  "context_before": "...",
  "context_after": "..."
}

Best Practices

Writing Effective Feedback

✅ 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."

❌ Avoid these patterns

Too vague:

"This section is unclear"  ❌

No context:

"Fix this"  ❌

Redundant:

"I implemented this"  ❌ (unless providing valuable context)

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

Use line numbers for precise locations

When you need exact positioning, especially in code-like specs

Use text search for sections

Anchor to section headings that are less likely to change

Skip anchor for general feedback

If feedback applies to entire spec, don’t anchor it

Keep anchors stable

Try to anchor to stable text (headings, not prose)

CLI Commands

Quick reference for feedback commands:

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

Feedback Command Reference

See complete documentation for all feedback commands

Common Workflows

Agent Discovers Ambiguity

Agent reads spec

sudocode spec show SPEC-001

Agent starts work

sudocode issue update ISSUE-042 --status in_progress

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

Human Reviews Feedback

Check for open feedback

sudocode feedback list --status open

Review specific feedback

sudocode feedback show FB-001

Update spec if needed

Edit the spec to address the feedback

Dismiss feedback

sudocode feedback dismiss FB-001 \
  --comment "Updated spec section 3.2 with token policy"

Next Steps

Specs

Learn about specs - the documents that receive feedback

Issues

Learn about issues - the source of implementation feedback

Workflows

See feedback in action in spec-driven development

Feedback Commands

Complete CLI reference for feedback commands

​What Is Feedback?

​Feedback vs. Relationships

Feedback

Relationships

​Feedback Types

​Smart Anchoring

​Line Number Anchoring

​Text Search Anchoring

​No Anchor (General Feedback)

​Anchor Relocation (Future)

​Creating Feedback

​Command Syntax

​Examples

​Viewing Feedback

​On Specs

​On Issues

​Agent Workflows

​When Agents Should Provide Feedback

​Example Agent Flow

​Managing Feedback

​Dismissing Feedback

​Listing Feedback

​Database Schema

​Best Practices

​Writing Effective Feedback

​When to Use Each Feedback Type

​Anchoring Best Practices

​CLI Commands

Feedback Command Reference

​Common Workflows

​Agent Discovers Ambiguity

​Human Reviews Feedback

​Next Steps

Specs

Issues

Workflows

Feedback Commands

What Is Feedback?

Feedback vs. Relationships

Feedback Types

Smart Anchoring

Line Number Anchoring

Text Search Anchoring

No Anchor (General Feedback)

Anchor Relocation (Future)

Creating Feedback

Command Syntax

Examples

Viewing Feedback

On Specs

On Issues

Agent Workflows

When Agents Should Provide Feedback

Example Agent Flow

Managing Feedback

Dismissing Feedback

Listing Feedback

Database Schema

Best Practices

Writing Effective Feedback

When to Use Each Feedback Type

Anchoring Best Practices

CLI Commands

Common Workflows

Agent Discovers Ambiguity

Human Reviews Feedback

Next Steps