outfitter-dev Firewatch Guide
Query GitHub PR activity and manage review feedback using the Firewatch CLI (fw) or MCP tools.
Quick Start
# Check setup
fw doctor
# View status (auth, cache, repo)
fw status --short
# Get per-PR summary
fw --summary
# See unaddressed feedback
fw fb
Core Concepts
Short IDs: Firewatch generates human-friendly short IDs (e.g., @a7f3c) for comments. Use these instead of long GitHub IDs.
JSONL Output: Default output is newline-delimited JSON. Pipe to jq for filtering. Use --no-jsonl for human-readable format.
Auto-sync: Cache refreshes automatically if stale. Use --no-sync to skip or --sync-full to force a full sync.
Triage Workflow
Systematic review to identify what needs attention.
1. Get Overview
# Per-PR summary with activity counts
fw --summary
# Compact summary
fw --summary --no-jsonl
2. Identify Priorities
P0 - Immediate:
# Changes requested on your PRs
fw --mine --type review | jq 'select(.body | contains("changes"))'
# Unaddressed feedback on your PRs
fw fb --repo owner/repo
P1 - Today:
# Approved PRs ready to merge
fw --summary | jq 'select(.review_states.approved > 0)'
# PRs needing your review
fw --reviews --summary
P2 - This Week:
# Stale PRs (no activity in 3+ days)
fw --summary | jq 'select(.last_activity_at < (now - 259200 | todate))'
# Orphaned comments (unresolved on merged PRs)
fw --orphaned
3. Graphite Stack Awareness
# PRs with stack metadata
fw --summary | jq 'select(.graphite != null)'
# Blocked stacks (lower PR has issues)
fw --summary | jq 'select(.graphite.stack_position > 1) | select(.review_states.changes_requested > 0)'
Address stack issues bottom-up to avoid merge conflicts.
4. Present Findings
Format triage output for the user:
## Needs Immediate Attention
- PR #123: Changes requested by @reviewer (2h ago)
- PR #456: CI failing
## Ready to Merge
- PR #789: Approved, all checks passing
## Review Requests
- PR #101: @author requested your review (1d ago)
Response Workflow
Systematic approach to addressing PR feedback.
1. List Feedback
# All unaddressed feedback (repo-wide)
fw fb
# Feedback for specific PR
fw fb 123
# All comments including resolved
fw fb 123 --all
2. View Comment Details
# View by short ID
fw fb @a7f3c
3. Address and Reply
After fixing code:
# Reply to comment
fw fb @a7f3c "Fixed in latest commit"
# Reply and resolve thread
fw fb @a7f3c "Done" --resolve
For clarification only:
# Just reply
fw fb @a7f3c "Good question! I chose X because..."
Acknowledge without action:
# Add thumbs-up reaction + local ack
fw fb @a7f3c --ack
# Bulk ack all feedback on a PR
fw fb 123 --ack
4. Resolve Without Reply
# Resolve thread directly
fw fb @a7f3c --resolve
5. Commit and Push
With Graphite:
gt modify -m "Address review feedback"
gt submit --stack
Standard git:
git add -A && git commit -m "Address review feedback" && git push
Comment Categories
| Type | Action |
|---|---|
| Bug/logic error | Fix code, reply explaining fix |
| Style/preference | Apply if reasonable, or discuss tradeoffs |
| Question | Reply with explanation (no code change) |
| Nitpick | Fix quickly or ack for future |
Response Templates
Code Fixed:
Fixed in [commit]. [Brief explanation].
Clarification:
Good question! [Explanation]. I chose this because [reasoning].
Acknowledged:
Good point, I'll address this in a follow-up PR.
Disagreement:
I considered that, but [reasoning]. Happy to discuss further.
CLI Quick Reference
| Command | Purpose |
|---|---|
fw |
Query activity (auto-syncs if stale) |
fw --summary |
Per-PR aggregation |
fw fb |
List/view/reply/resolve feedback |
fw fb 123 |
Feedback for PR #123 |
fw fb @id "text" |
Reply to comment |
fw fb @id --resolve |
Resolve thread |
fw pr edit 123 --title "..." |
Edit PR fields |
fw status |
Auth/cache/repo info |
fw doctor |
Diagnose issues |
fw schema entry |
Output format schema |
See references/cli.md for complete command documentation.
MCP Tools Quick Reference
| Tool | Purpose |
|---|---|
fw_query |
Query cached activity |
fw_fb |
Feedback operations |
fw_pr |
PR mutations (edit/rm/review) |
fw_status |
Status info |
fw_doctor |
Diagnostics |
fw_help |
Usage docs |
See references/mcp.md for complete tool documentation.
Common Filters
# By time
fw --since 24h
fw --since 7d
# By type
fw --type review
fw --type comment
# By PR state
fw --open # Open PRs only
fw --draft # Drafts only
fw --open # Open + draft
fw --closed # Merged + closed
# By ownership
fw --mine # My PRs
fw --reviews # PRs I need to review
# Exclude bots
fw --no-bots
Checklist
Before marking review complete:
- All comments addressed or responded to
- Code changes committed and pushed
- Threads resolved where appropriate
- CI passing on latest commit
Further Reading
- references/cli.md - Complete CLI reference
- references/mcp.md - MCP tool reference
- references/troubleshooting.md - Setup and troubleshooting
- examples/triage.md - Triage workflow examples
- examples/respond.md - Response workflow examples
- examples/jq-patterns.md - Common jq queries