asets-gobizit/review-issues

Review Issues

Review all Paperclip issues needing your attention. Approve agent work ("Helpful") or send it back with feedback ("Needs Work") — all from inside Claude Code.

When to Use

• User says "review issues", "review paperclip", "check issues", "/review-issues"
• User wants to approve or amend agent work in Paperclip
• User asks "what issues need my attention?"

HOW TO INVOKE

Just say /review-issues or "review my paperclip issues".

API Base

All API calls use http://127.0.0.1:3100/api with no auth header (local_trusted mode grants board access automatically).

Execution Recipe

Follow these steps exactly. Use curl -s for all API calls.

Step 1: Discover Companies and Agents

# Get all companies
curl -s http://127.0.0.1:3100/api/companies

For each company returned, fetch agents to build a name lookup:

# Get agents for a company (replace {companyId})
curl -s http://127.0.0.1:3100/api/companies/{companyId}/agents

Build a map: agentId → agent.name so you can display human-readable names.

Step 2: Fetch Issues

For each company, fetch both statuses:

curl -s "http://127.0.0.1:3100/api/companies/{companyId}/issues?status=todo"
curl -s "http://127.0.0.1:3100/api/companies/{companyId}/issues?status=in_review"

Merge all results. Separate into two buckets:

• Agent Work — issues where assigneeAgentId is set (not null). These are agent outputs for the user to review.
• Your Items — issues where assigneeUserId == "local-board" and assigneeAgentId is null. These are the user's own action items.

Sort agent work by priority: critical > high > medium > low.

Step 3: Present Dashboard

Show a summary like this:

Paperclip Issue Review
━━━━━━━━━━━━━━━━━━━━━

CompanyName: X in_review, Y todo (agent work)
Your action items: Z

Agent Work (review these):
 1. GOB-6   Legal Strategy           [in_review] → Legal Advisor
 2. GOB-11  Prospect List            [todo]      → BizDev Manager
 ...

Your Items (FYI):
 1. GOB-19  Danny Action Items       [todo]
 2. GOB-21  CEO Proposals            [todo]

Then ask: "Review all agent work sequentially, pick specific issues by number, or skip to a specific one?"

Step 4: Per-Issue Review

For each issue being reviewed, fetch details:

# Get plan document (if exists)
curl -s http://127.0.0.1:3100/api/issues/{issueId}/documents

# If a document with key "plan" exists, get its content:
curl -s http://127.0.0.1:3100/api/issues/{issueId}/documents/plan

# Get document revisions (needed for feedback targetId):
curl -s http://127.0.0.1:3100/api/issues/{issueId}/documents/plan/revisions

# Get comments (last 3)
curl -s http://127.0.0.1:3100/api/issues/{issueId}/comments

Present the issue:

═══════════════════════════════════════════
GOB-11: Build SMB prospect list (High)
Assigned to: BizDev Manager | Status: todo
───────────────────────────────────────────
Description:
[issue description, max 300 chars with ...]
───────────────────────────────────────────
Plan Document:
[full plan doc body if exists, or "No plan document"]
───────────────────────────────────────────
Recent Comments (N):
 • [BizDev Manager] Blocked pending tool access...
 • [BizDev Manager] Week 1 Kickoff started...
═══════════════════════════════════════════

What would you like to do? Approve, Amend, or Skip?

Step 5a: Approve

When the user approves:

1. Determine feedback target:

   • If plan document exists: use the latest revision ID from the revisions endpoint. targetType = "issue_document_revision", targetId = <latest revision id>
   • Else if comments exist: use the latest comment ID. targetType = "issue_comment", targetId = <latest comment id>
   • If neither exists: skip the feedback vote (just mark done).

2. Post feedback vote:

curl -s -X POST http://127.0.0.1:3100/api/issues/{issueId}/feedback-votes \
  -H "Content-Type: application/json" \
  -d '{"targetType": "issue_document_revision", "targetId": "<id>", "vote": "up"}'

3. Mark issue done:

curl -s -X PATCH http://127.0.0.1:3100/api/issues/{issueId} \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

4. Report: "GOB-11 approved and marked done."

Step 5b: Amend

When the user wants to amend:

1. Ask for feedback: "What feedback do you have for the agent?"

2. Wait for user's response — they can give detailed natural language feedback.

3. Determine feedback target (same logic as Approve).

4. Post feedback vote with reason:

curl -s -X POST http://127.0.0.1:3100/api/issues/{issueId}/feedback-votes \
  -H "Content-Type: application/json" \
  -d '{"targetType": "issue_document_revision", "targetId": "<id>", "vote": "down", "reason": "<user feedback>"}'

5. Post comment + handle reopen:

   If issue status is done or cancelled — use reopen flag:

curl -s -X POST http://127.0.0.1:3100/api/issues/{issueId}/comments \
  -H "Content-Type: application/json" \
  -d '{"body": "## Board Feedback\n\n<user feedback>\n\n---\n**What could have been better:** <user feedback>", "reopen": true}'

If issue status is todo or in_review — set status explicitly + post comment without reopen:

curl -s -X PATCH http://127.0.0.1:3100/api/issues/{issueId} \
  -H "Content-Type: application/json" \
  -d '{"status": "todo"}'

curl -s -X POST http://127.0.0.1:3100/api/issues/{issueId}/comments \
  -H "Content-Type: application/json" \
  -d '{"body": "## Board Feedback\n\n<user feedback>\n\n---\n**What could have been better:** <user feedback>"}'

Note: The comment POST automatically triggers an agent wakeup (built into Paperclip) — no need to call wakeup separately.

6. Report: "GOB-11 sent back to BizDev Manager with your feedback. Agent will be woken to address it."

Step 5c: Skip

Move to the next issue in the queue.

Error Handling

• Paperclip offline: If curl to port 3100 fails, tell the user: "Paperclip is not running. Start it with: powershell Start-ScheduledTask -TaskName PaperclipAI"
• No issues found: "No issues in todo or in_review status. All clear!"
• Feedback vote fails with 404: The issue may have been deleted. Skip and move to next.
• PATCH returns 409 (conflict): Another run has the issue checked out. Tell the user and skip.

Important Notes

• Never use the -d flag with shell variables or user text that might contain quotes. Always use the Write tool to create a temp JSON file if the feedback text is complex, then curl -d @file.json.
• The reason field in feedback-votes is max 1000 chars. Truncate if needed.
• Agent names come from the /agents endpoint, not from the issue itself.
• Comments posted by agents have agentId set; comments by the user have userId set.