feedback-patterns

name	feedback-patterns
description	Patterns for providing structured feedback that closes the loop between implementation and requirements. Use when closing issues, documenting implementation decisions, or updating specs with learnings.

Feedback Patterns

Guidelines for providing effective feedback that connects implementation back to requirements.

When to Use

• Closing an issue that implements a spec
• Documenting design decisions made during implementation
• Reporting challenges or blockers encountered
• Suggesting spec improvements based on implementation experience
• Requesting clarification on ambiguous requirements

Feedback Principles

1. Close the Loop

Feedback connects implementation back to requirements, creating a knowledge cycle.

Spec (requirements) → Issue (work) → Implementation → Feedback → Spec (updated)

2. Anchor to Specific Content

Feedback is most useful when tied to specific parts of the spec.

❌ BAD: "The spec was unclear"

✅ GOOD: Feedback anchored to line 45 of the spec:
"The phrase 'handle edge cases' needs specifics.
During implementation, I encountered: empty input,
null values, and timeout scenarios."

3. Include Evidence

Back up feedback with concrete observations.

❌ BAD: "It works"

✅ GOOD: "Requirements met:
- 47 tests passing (100% of acceptance criteria)
- Load tested to 1000 concurrent users
- Verified in staging environment"

4. Be Actionable When Needed

Suggestions and requests should be specific enough to act on.

❌ BAD: "Spec should be better"

✅ GOOD: "Suggestion: Add a 'Rate Limiting' section
covering: requests per minute limit, response format
for rate-limited requests, and retry-after header."

---

Feedback Types

Type	Purpose	When to Use	Action Required
comment	Informational	Document what happened	None (documentation)
suggestion	Spec improvement	Found gap or improvement	Update spec
request	Clarification needed	Ambiguity blocking work	User input needed

Comment (Informational)

Use for documenting what was done, decisions made, and outcomes.

Type: comment

Content:
Implemented OAuth login per spec requirements.

Decisions made:
- Used PKCE flow for security (not explicitly required but best practice)
- Token refresh happens 5 minutes before expiry (spec said "before expiry")
- Stored tokens in httpOnly cookies (spec was flexible on storage)

Evidence:
- 23 unit tests, 5 integration tests passing
- Tested with Google, GitHub, and Microsoft providers
- Security review passed

Suggestion (Spec Improvement)

Use when you've found something that should be added or changed in the spec.

Type: suggestion

Anchor: Line 34 ("Handle authentication errors gracefully")

Content:
Suggest adding specific error scenarios to handle:

1. **Token expired during request**
   - Current behavior: 401 response
   - Suggested: Auto-retry with refreshed token

2. **Provider unavailable**
   - Current behavior: Generic error
   - Suggested: Specific error code + fallback options

3. **Invalid state parameter**
   - Current behavior: Silent failure
   - Suggested: Security alert + session termination

These scenarios came up during implementation and testing.
Having them in the spec would help future maintainers.

Request (Clarification Needed)

Use when you need user input to proceed correctly.

Type: request

Anchor: Line 56 ("Support multiple authentication methods")

Content:
Clarification needed on priority and UX:

1. **Method priority**: If user has both password and OAuth,
   which takes precedence for login?

2. **Account linking**: Can users link multiple OAuth providers
   to one account? Or one provider per account?

3. **Migration path**: For existing password users, is OAuth
   optional or should we prompt them to add it?

Currently blocked on these decisions. Implemented password-first
as temporary approach, but this may need to change.

---

Feedback Structure

Standard Template

## Requirements Met
[What was implemented according to spec]

## Design Decisions
[Choices made during implementation with rationale]

## Challenges Encountered
[Problems faced and how they were resolved]

## Evidence
[Tests, metrics, observations proving completion]

## Suggestions
[Improvements to the spec based on learnings]

## Discovered Work
[New issues/specs that emerged]

Compact Template (for small issues)

✅ **Done:** [What was completed]
📝 **Decisions:** [Key choice made]
🔗 **Related:** [[i-xxxx]] discovered during work

Detailed Template (for complex implementations)

# Feedback: [Issue Title] → [[s-xxxx]]

## Summary
[One paragraph overview of implementation]

## Requirements Analysis

| Requirement | Status | Notes |
|-------------|--------|-------|
| Req 1 | ✅ Met | Implemented as specified |
| Req 2 | ✅ Met | Minor deviation (see below) |
| Req 3 | ⚠️ Partial | Blocked by external dependency |

## Design Decisions

### Decision 1: [Title]
**Context:** [Why this decision was needed]
**Options:** [What was considered]
**Choice:** [What was chosen]
**Rationale:** [Why]

### Decision 2: [Title]
...

## Challenges & Resolutions

### Challenge 1: [Title]
**Problem:** [What went wrong]
**Impact:** [How it affected work]
**Resolution:** [How it was fixed]

### Challenge 2: [Title]
...

## Evidence

### Testing
- Unit tests: X passing
- Integration tests: X passing
- Coverage: X%

### Verification
- [ ] Verified in development
- [ ] Verified in staging
- [ ] Performance benchmarked

### Metrics
- Response time: Xms (target: Yms)
- Error rate: X% (target: <Y%)

## Suggestions for Spec

### Suggestion 1
**Location:** [Line/section reference]
**Current:** [What spec says]
**Suggested:** [What it should say]
**Rationale:** [Why this change]

## Discovered Work

- [[i-xxxx]] - [Description] (created during implementation)
- [[s-yyyy]] - [Description] (new spec needed)

---

Anchoring Strategies

Line-Based Anchoring

Most precise, but may become stale if spec changes.

add_feedback({
  to_id: "s-auth",
  type: "suggestion",
  line: 45,
  content: "This requirement needs clarification..."
})

Text-Based Anchoring

Finds the text and anchors there, more resilient to changes.

add_feedback({
  to_id: "s-auth",
  type: "comment",
  text: "Support OAuth 2.0 providers",
  content: "Implemented with Google, GitHub, Microsoft..."
})

Section-Based Anchoring

Anchors to a heading/section, good for broad feedback.

add_feedback({
  to_id: "s-auth",
  type: "suggestion",
  text: "## Security Requirements",
  content: "Consider adding rate limiting section..."
})

No Anchor (Spec-Level)

For feedback about the entire spec.

add_feedback({
  to_id: "s-auth",
  type: "comment",
  content: "Overall implementation complete. See details..."
})

---

Processing Feedback

Feedback Triage Workflow

1. LIST FEEDBACK
   show_spec <id>  # Includes feedback section

2. TRIAGE EACH ITEM
   For each feedback:

   TYPE: comment
   → Acknowledge, no action needed
   → May inform future work

   TYPE: suggestion
   → Evaluate: Is this a valid improvement?
   → YES: Update spec, mark addressed
   → NO: Respond with rationale

   TYPE: request
   → Provide clarification
   → Update spec with clarification
   → Unblock related issues

3. UPDATE SPEC
   upsert_spec <id> with improvements

4. CREATE FOLLOW-UPS
   If feedback reveals new work:
   upsert_issue for discovered work
   link to original feedback

Feedback Status

Feedback can become stale when specs change:

Status	Meaning	Action
valid	Anchor still matches	Review and address
relocated	Found at different location	Verify still relevant
stale	Anchor not found	Manual review needed

---

Good vs Bad Feedback

Requirements Met

❌ BAD:
"Done."

✅ GOOD:
"Requirements met:
- User can log in with email/password ✅
- Session persists across page refresh ✅
- Logout clears session completely ✅
- Invalid credentials show specific error ✅

All 4 acceptance criteria verified with automated tests."

Design Decisions

❌ BAD:
"Made some choices during implementation."

✅ GOOD:
"Design decisions:

1. **Token storage**: Chose httpOnly cookies over localStorage
   - Rationale: XSS protection, automatic inclusion in requests
   - Trade-off: Requires CSRF protection (added)

2. **Session duration**: Set to 7 days with sliding expiration
   - Rationale: Balance security with UX
   - Spec said 'reasonable duration' - clarified as 7 days"

Challenges

❌ BAD:
"Had some issues but figured it out."

✅ GOOD:
"Challenges encountered:

1. **Race condition in token refresh**
   - Problem: Multiple tabs could trigger simultaneous refresh
   - Impact: Occasional auth failures
   - Resolution: Added mutex lock on refresh operation
   - Prevention: Added to test suite

2. **OAuth state mismatch**
   - Problem: State parameter lost on mobile browsers
   - Impact: Login failed on iOS Safari
   - Resolution: Store state in sessionStorage as backup
   - Suggestion: Add mobile testing requirements to spec"

Suggestions

❌ BAD:
"Spec could be improved."

✅ GOOD:
"Suggestions for spec improvement:

1. **Add error code reference** (anchor: line 34)
   Current: 'Handle errors appropriately'
   Suggested: Add table of error codes:
   - AUTH001: Invalid credentials
   - AUTH002: Account locked
   - AUTH003: Session expired

2. **Clarify mobile behavior** (anchor: Security section)
   Current: Not mentioned
   Suggested: Add section on mobile-specific considerations:
   - Deep linking for OAuth callbacks
   - Biometric authentication option
   - Offline token handling"

---

Feedback Workflow Integration

When Closing an Issue

1. BEFORE CLOSING
   - Verify acceptance criteria met
   - Run verification loop
   - Prepare feedback content

2. PROVIDE FEEDBACK
   add_feedback to_id=<spec-id> type=comment content=<feedback>

3. CLOSE ISSUE
   upsert_issue <id> status=closed

4. CHECK NEXT WORK
   ready

Feedback Checklist

Before closing an issue that implements a spec:

□ Reviewed spec requirements
□ All acceptance criteria addressed
□ Design decisions documented
□ Challenges and resolutions noted
□ Evidence provided (tests, verification)
□ Suggestions for spec improvement (if any)
□ Discovered work captured as issues
□ Feedback anchored to relevant spec sections

---

Quick Reference

Providing Feedback

// Comment (informational)
add_feedback({
  to_id: "s-xxxx",
  type: "comment",
  content: "Implementation complete. [details]"
})

// Suggestion (spec improvement)
add_feedback({
  to_id: "s-xxxx",
  type: "suggestion",
  line: 45,  // or text: "section heading"
  content: "Suggest adding [X] because [Y]"
})

// Request (clarification needed)
add_feedback({
  to_id: "s-xxxx",
  type: "request",
  text: "ambiguous requirement text",
  content: "Need clarification on [X]. Options are [A, B, C]."
})

Viewing Feedback

show_spec <id>       # Shows spec with all feedback

---

Remember: Feedback is how implementations improve specs, and specs improve future implementations. Good feedback creates a virtuous cycle of learning. Poor feedback (or no feedback) means the same mistakes get repeated.