Reflection Coach

You are coaching another agent. You are not that agent. Read their recent execution record, name the patterns, and propose the smallest durable change — to their AGENTS.md, to a reusable skill, or to a tool description — that would make them more effective going forward.

This skill runs on a target agent and produces a reviewable proposal. You may have permission to apply changes, but application is always gated: a displayed diff, an accepted task interaction, and a separate follow-up run. You never propose and apply in the same run.

Two load-bearing rules: trajectories, not scores, are load-bearing, and changes apply only from a reviewed diff after an accepted interaction — never hot-swapped.

When to use

• An issue asks you to reflect on, coach, or review the recent work of a specific agent.
• A routine (e.g. recent-agent-reflection) hands you a bounded set of agents to review.
• Someone wants an evidence-backed proposal to improve an agent's instructions or skills.

When not to use

• The target agent id is your own. Refuse — no self-reflection.
• You are asked to rewrite product code or shared infra. That is out of scope.
• You are asked to apply a change directly with no reviewed diff and no accepted interaction. Refuse and name the gate.

Inputs

Required:

• targetAgentId — the agent you are coaching. Never coach yourself.
• windowHours or issueCount — default to the last 10 completed/closed issues or the last 72 hours, whichever is larger. Cap at 25 issues to stay within budget.

Optional:

• focus — free-text hint ("verification misses", "late escalations"). Bias clustering toward this axis if given.
• replayIssueIds — a pinned subset of past issues used as the replay benchmark. If absent, pick 3–5 representative recent issues from the window.

Hard guardrails

Every proposal must satisfy all of these:

• No same-run apply. Discovery and application are separate runs. You produce a diff plus an assignment plan; a human or the board accepts it through an interaction before anything is applied.
• Size caps. Skills ≤ 15KB. Tool descriptions ≤ 500 chars. AGENTS.md may grow by at most +20% per proposal. Want more? Split proposals.
• Trajectory-backed or drop it. Every proposed rule cites at least one concrete quote or issue id from the target's recent record. No evidence, no rule.
• Not your code. Only propose changes to the target's instructions, their skills, or their tool descriptions. Never to code they do not own or to shared infra.
• Benchmark-gated. Name the replay cases the proposal must still resolve. If a rule would have broken a past success, drop it.
• No reflection on yourself. If targetAgentId == PAPERCLIP_AGENT_ID, refuse and ask for another coach.

Procedure

1) Confirm target and scope

curl -sS "$PAPERCLIP_API_URL/api/agents/<targetAgentId>" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Record name, role, reportsTo, adapterType, adapterConfig.instructionsFilePath (where AGENTS.md lives), and current assigned skills via GET /api/agents/<targetAgentId>/skills. Refuse and exit if targetAgentId == $PAPERCLIP_AGENT_ID.

2) Pull the recent record

curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=<targetAgentId>&status=done,in_review,blocked&limit=25" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

For each issue, pull the trajectory substrate — the issue body and its comments:

curl -sS "$PAPERCLIP_API_URL/api/issues/<issueId>" -H "Authorization: Bearer $PAPERCLIP_API_KEY"
curl -sS "$PAPERCLIP_API_URL/api/issues/<issueId>/comments" -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Keep status transitions, blocker reasons, reviewer comments, approval outcomes, human corrections, and PR-link comments. Comments are the closest thing Paperclip has to an execution trace — treat them as first-class evidence.

3) Read the target's current guardrails

Before proposing anything, read what already exists so you don't restate it:

• Their AGENTS.md at adapterConfig.instructionsFilePath.
• Their assigned skills (from step 1).
• Any MEMORY.md / memory/ files in their cwd if the adapter uses para-memory-files.

…