Explore 'feedback' as unifying terminology for PR activity

[galligan]

Summary

Explore consolidating terminology around "feedback" as the primary user-facing term for all PR comments, reviews, and review comments that require attention.

Current State

The codebase uses multiple overlapping terms at different conceptual levels:

Terminology Layers (Current)

Level	Term	Where Used	Meaning
Umbrella	"PR activity"	README, SPEC, high-level docs	Everything Firewatch captures
Technical	"entry types"	Schema, code	comment, review, commit, ci, event
Subtypes	"comment subtypes"	Schema, filters	review_comment, issue_comment
User-facing	"feedback"	CLI (fb, ack, close), actionable.ts	Unaddressed items needing response

Evidence from Codebase

Code defines "feedback" specifically (apps/cli/src/actionable.ts:35-47):

export interface UnaddressedFeedback {
  repo: string;
  pr: number;
  comment_id: string;
  author: string;
  body?: string;
  file?: string;
  line?: number;
  // ...
}

CLI uses "feedback" in user-facing commands:

• fw fb - "Feedback abstraction: list, view, reply, resolve"
• fw ack - "Acknowledge feedback comments (local + optional reaction)"
• fw close - "Close feedback: resolve review threads or close PRs"

Config has feedback-specific settings (packages/core/src/schema/config.ts:28-38):

export const FeedbackConfigSchema = z.object({
  commit_implies_read: z.boolean().default(false),
});

Problem

1. Terminology confusion: Users must learn multiple terms (activity, entry, comment, review, review_comment, issue_comment, feedback) to understand what Firewatch tracks

2. GitHub complexity hidden poorly: GitHub has:

   • PullRequestReview (the review submission with approve/changes_requested state)
   • PullRequestReviewComment (inline code comments, can be resolved)
   • IssueComment (general PR discussion, cannot be resolved)

   We expose this as type: comment | review with subtype: review_comment | issue_comment - which mirrors GitHub's complexity rather than simplifying it

3. What matters is obscured: Users care about "what needs my attention" - the answer is feedback, but we make them think in GitHub API terms

Proposal

Elevate "feedback" as the primary user-facing term:

What is Feedback?

Feedback is any PR comment or review that requests action from the author. This includes:

• Review comments (inline code comments)
• Issue comments (PR discussion)
• Reviews with "changes requested" state

Proposed Changes

1. Documentation: Use "feedback" consistently in user-facing docs

   • Create docs/GLOSSARY.md with clear definitions
   • Update README to emphasize feedback-centric workflow
   • Clarify that fw fb = "firewatch feedback"

2. CLI help text improvements:

   # Current
   fb - "Feedback abstraction: list, view, reply, resolve"
   
   # Proposed  
   fb - "Manage feedback: list, view, reply to, and resolve PR comments"
   

3. Consider filter simplification:

   # Current: requires knowing subtypes
   fw --type comment --subtype review_comment
   
   # Possible future: feedback-centric
   fw --feedback          # all feedback items
   fw --feedback inline   # review_comment only
   fw --feedback discuss  # issue_comment only

4. Schema documentation: Keep technical accuracy but lead with user intent:

   ## Entry Types
   
   ### Feedback Types (what needs your attention)
   - `review_comment` - Inline code feedback on specific lines
   - `issue_comment` - General PR discussion
   - `review` (changes_requested) - Review requesting changes
   
   ### Activity Types (for context)
   - `review` - Review submissions (approve, comment, etc.)
   - `commit` - Commits to the PR
   - `ci` - CI/CD status
   - `event` - PR lifecycle (opened, merged, etc.)
   

Non-Goals

• Changing internal type names (EntryType, subtype values)
• Breaking existing CLI flags or JSONL output
• Removing technical precision for power users

Questions to Explore

1. Should fw feedback be an alias for fw fb?
2. Should we add a --feedback filter that combines comment types?
3. How do we handle review type with state=changes_requested (it's feedback but different from comments)?
4. Should the worklist/summary output group by "feedback" vs "activity"?

Related Files

• apps/cli/src/actionable.ts - UnaddressedFeedback interface
• apps/cli/src/commands/fb.ts - Feedback command
• packages/core/src/schema/entry.ts - Entry type definitions
• packages/core/src/schema/config.ts - FeedbackConfig
• docs/schema.md - Entry type documentation
• .claude/skills/firewatch/ - Plugin documentation

---

/cc @galligan