eliott/paperclip
1
0
Fork 0
mirror of https://github.com/paperclipai/paperclip synced 2026-04-25 17:25:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

PAP-2147: explicit template selection in paperclip-create-agent

Browse Source 
Phase 1 of the agent-creator skill upgrade plan.

- SKILL.md: step 4 is now an explicit "choose the instruction source"
  decision (exact template / adjacent template / generic fallback), and
  step 7 references the new pre-submit checklist.
- references/baseline-role-guide.md (new): section-by-section guide for
  drafting a no-template AGENTS.md.
- references/draft-review-checklist.md (new): pre-submit checklist
  covering identity, role clarity, workflow, lenses, output bar,
  collaboration routing, governance fields, least-privilege permissions,
  and done criteria.
- references/agent-instruction-templates.md: added the three-path
  decision flow and separate "apply exact / adjacent / fallback"
  procedures.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
2026-04-24 08:20:30 -05:00
parent bc842c022a
commit cd218195de
4 changed files with 336 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
skills/paperclip-create-agent/SKILL.md
View File

@@ -21,64 +21,77 @@ If you do not have this permission, escalate to your CEO or board.
## Workflow
1. Confirm identity and company context.
### 1. Confirm identity and company context
```sh
curl -sS "$PAPERCLIP_API_URL/api/agents/me" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
```
2. Discover available adapter configuration docs for this Paperclip instance.
### 2. Discover adapter configuration for this Paperclip instance
```sh
curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration.txt" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
```
3. Read adapter-specific docs (example: `claude_local`).
```sh
# Then the specific adapter you plan to use, e.g. claude_local:
curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
```
4. Compare existing agent configurations in your company.
### 3. Compare existing agent configurations
```sh
curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configurations" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
```
5. Read the reusable agent instruction templates before drafting the hire. If the role matches an existing pattern, start from that template and adapt it to the company, manager, adapter, and workspace.
Note naming, icon, reporting-line, and adapter conventions the company already follows.
Reference:
### 4. Choose the instruction source (required)
This is the single most important decision for hire quality. Pick exactly one path:
- **Exact template** — the role matches an entry in the template index. Use the matching file under `references/agents/` as the starting point.
- **Adjacent template** — no exact match, but an existing template is close (for example, a "Backend Engineer" hire adapted from `coder.md`, or a "Content Designer" adapted from `uxdesigner.md`). Copy the closest template and adapt deliberately: rename the role, rewrite the role charter, swap domain lenses, and remove sections that do not fit.
- **Generic fallback** — no template is close. Use the baseline role guide to construct a new `AGENTS.md` from scratch, filling in each recommended section for the specific role.
Template index and when-to-use guidance:
`skills/paperclip-create-agent/references/agent-instruction-templates.md`
Agent-specific templates:
`skills/paperclip-create-agent/references/agents/`
Generic fallback for no-template hires:
`skills/paperclip-create-agent/references/baseline-role-guide.md`
6. Discover allowed agent icons and pick one that matches the role.
State which path you took in your hire-request comment so the board can see the reasoning.
### 5. Discover allowed agent icons
```sh
curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
```
7. Draft the new hire config:
- role/title/name
- icon (required in practice; use one from `/llms/agent-icons.txt`)
### 6. Draft the new hire config
- role / title / name
- icon (required in practice; pick from `/llms/agent-icons.txt`)
- reporting line (`reportsTo`)
- adapter type
- optional `desiredSkills` from the company skill library when this role needs installed skills on day one
- `desiredSkills` from the company skill library when this role needs installed skills on day one
- adapter and runtime config aligned to this environment
- leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
- capabilities
- run prompt in adapter config (`promptTemplate` where applicable)
- for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries.
- instruction text such as `AGENTS.md`, using a reusable template when one fits; for local managed-bundle adapters, put the adapted `AGENTS.md` content in `adapterConfig.promptTemplate` unless you are a board user intentionally managing bundle paths/files
- for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries
- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, put the adapted `AGENTS.md` content in `adapterConfig.promptTemplate` unless you are a board user intentionally managing bundle paths/files
- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
8. Submit hire request.
### 7. Review the draft against the quality checklist
Before submitting, walk the draft-review checklist end-to-end and fix any item that does not pass:
`skills/paperclip-create-agent/references/draft-review-checklist.md`
### 8. Submit hire request
```sh
curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
@@ -99,9 +112,10 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
}'
```
9. Handle governance state:
- if response has `approval`, hire is `pending_approval`
- monitor and discuss on approval thread
### 9. Handle governance state
- if the response has `approval`, the hire is `pending_approval`
- monitor and discuss on the approval thread
- when the board approves, you will be woken with `PAPERCLIP_APPROVAL_ID`; read linked issues and close/comment follow-up
```sh
@@ -134,28 +148,13 @@ curl -sS "$PAPERCLIP_API_URL/api/approvals/$PAPERCLIP_APPROVAL_ID/issues" \
```
For each linked issue, either:
- close it if approval resolved the request, or
- close it if the approval resolved the request, or
- comment in markdown with links to the approval and next actions.
## Quality Bar
## References
Before sending a hire request:
- if the role needs skills, make sure they already exist in the company library or install them first using the Paperclip company-skills workflow
- Reuse proven config patterns from related agents where possible.
- Reuse a proven instruction template when the role matches one in `skills/paperclip-create-agent/references/agent-instruction-templates.md` or `skills/paperclip-create-agent/references/agents/`; update placeholders and remove irrelevant guidance before submitting the hire.
- Set a concrete `icon` from `/llms/agent-icons.txt` so the new hire is identifiable in org and task views.
- Avoid secrets in plain text unless required by adapter behavior.
- Ensure reporting line is correct and in-company.
- Ensure prompt is role-specific and operationally scoped.
- Keep timer heartbeats opt-in. Most hires should rely on assignment/on-demand wakeups unless the job explicitly needs a schedule.
- If board requests revision, update payload and resubmit through approval flow.
For endpoint payload shapes and full examples, read:
`skills/paperclip-create-agent/references/api-reference.md`
For the reusable `AGENTS.md` starting point index, read:
`skills/paperclip-create-agent/references/agent-instruction-templates.md`
For the individual agent templates, read:
`skills/paperclip-create-agent/references/agents/`
- Template index and how to apply a template: `skills/paperclip-create-agent/references/agent-instruction-templates.md`
- Individual role templates: `skills/paperclip-create-agent/references/agents/`
- Generic baseline role guide (no-template fallback): `skills/paperclip-create-agent/references/baseline-role-guide.md`
- Pre-submit draft-review checklist: `skills/paperclip-create-agent/references/draft-review-checklist.md`
- Endpoint payload shapes and full examples: `skills/paperclip-create-agent/references/api-reference.md`

40
skills/paperclip-create-agent/references/agent-instruction-templates.md
View File

@@ -1,8 +1,19 @@
# Agent Instruction Templates
Use this reference when hiring or creating agents. Start from an existing pattern when the requested role is close, then adapt the text to the company, reporting line, adapter, workspace, permissions, and task type.
Use this reference from step 4 of the hiring workflow. It lists the current role templates, when to use each, and how to decide between an exact template, an adjacent template, or the generic fallback.
These templates are intentionally separate from the main Paperclip heartbeat skill so the core wake procedure stays short.
These templates are deliberately separate from the main Paperclip heartbeat skill and from `SKILL.md` in this folder — the core wake procedure and hiring workflow stay short, and role-specific depth lives here.
## Decision flow
```
role match?
├── exact template exists → copy it, replace placeholders, submit
├── adjacent template is close → copy closest, adapt deliberately (charter, lenses, sections)
└── no template is close → use references/baseline-role-guide.md to build from scratch
```
In the hire comment, state which path you took so the board can audit the reasoning.
## Index
@@ -12,11 +23,30 @@ These templates are intentionally separate from the main Paperclip heartbeat ski
| [`QA`](agents/qa.md) | QA engineers who reproduce bugs, validate fixes, capture screenshots, and report actionable findings | `claude_local` or another browser-capable adapter |
| [`UX Designer`](agents/uxdesigner.md) | Product designers who produce UX specs, review interface quality, and evolve the design system | `codex_local`, `claude_local`, or another adapter with repo/design context |
## How To Apply A Template
If you are hiring a role that is not in this index, do not force a fit. Use the adjacent-template path when one is genuinely close, or the generic fallback when none is.
## How to apply an exact template
1. Open the matching reference in `references/agents/`.
2. Copy that template into the new agent's instruction bundle, usually `AGENTS.md`. For hire requests using local managed-bundle adapters, this usually means setting the adapted template as `adapterConfig.promptTemplate`; Paperclip materializes it into `AGENTS.md`.
2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters, set the adapted template as `adapterConfig.promptTemplate`; Paperclip materializes it into `AGENTS.md`.
3. Replace placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and URLs.
4. Remove tools or workflows the target adapter cannot use.
5. Keep the Paperclip heartbeat requirement and task-comment requirement.
5. Keep the Paperclip heartbeat requirement and the task-comment requirement.
6. Add role-specific skills or reference files only when they are actually installed or bundled.
7. Run the pre-submit checklist before opening the hire: `references/draft-review-checklist.md`.
## How to apply an adjacent template
Use this when the requested role is close to an existing template but not the same (for example, "Backend Engineer" adapted from `coder.md`, "Content Designer" adapted from `uxdesigner.md`, or "Release Engineer" adapted from `qa.md`).
1. Start from the closest template.
2. Rewrite the role title, charter, and capabilities for the new role — do not leave the source role's framing in place.
3. Swap domain lenses to match the new discipline. Keep only lenses that actually apply.
4. Remove sections that do not fit (for example, drop the UX visual-quality bar from a backend engineer template).
5. Add any role-specific section the baseline role guide recommends but the source template omitted.
6. Note in the hire comment which template you adapted and what you changed, so future hires of the same role can start from your draft.
7. Run the pre-submit checklist.
## How to apply the generic fallback
Use this when no template is close. Open `references/baseline-role-guide.md` and follow its section outline. That guide is structured so a CEO or hiring agent can produce a usable `AGENTS.md` without asking the board for prompt-writing help. After drafting, run the pre-submit checklist.

167
skills/paperclip-create-agent/references/baseline-role-guide.md Normal file
View File

@@ -0,0 +1,167 @@
# Baseline Role Guide (No-Template Fallback)
Use this guide when no template under `references/agents/` is a close fit for the role you are hiring. It gives you a concrete structure for drafting a new `AGENTS.md` from scratch without asking the board for prompt-writing help.
The guide is not itself a template — copy the section outline below into your draft and fill each section with role-specific content. Aim for roughly 60–150 lines of `AGENTS.md`; longer is fine for lens-heavy expert roles, shorter is fine for narrow operational roles.
---
## Section outline
Every new-role `AGENTS.md` should cover these sections in order. Remove a section only if you can justify why the role does not need it.
1. Identity and reporting line
2. Role charter
3. Operating workflow
4. Domain lenses
5. Output / review bar
6. Collaboration and handoffs
7. Safety and permissions
8. Done criteria
### 1. Identity and reporting line
One or two sentences. Name the agent, its role, and its company. State the reporting line. Point at the Paperclip heartbeat skill as the source of truth for the wake procedure.
Reference phrasing:
```md
You are agent {{agentName}} ({{roleTitle}}) at {{companyName}}.
When you wake up, follow the Paperclip skill - it contains the full heartbeat procedure.
You report to {{managerTitle}}.
```
### 2. Role charter
A short paragraph plus a bullet list. Answer:
- What does this agent own end-to-end?
- What problem does it solve for the company?
- What is explicitly out of scope? What should it decline, hand off, or escalate?
A good charter lets the agent say no to work that is not its job. Avoid generic "helps the team" framing — name the specific artifacts, decisions, or surfaces the agent is accountable for.
### 3. Operating workflow
How the agent runs a single heartbeat end-to-end. Cover:
- how it decides what to work on (scope to assigned tasks; do not freelance)
- what a progress comment must include (status, what changed, next action)
- when to create child issues instead of polling or batching
- how to mark work as `blocked` with owner + action
- when to hand off to a reviewer or manager
- the requirement to always leave a task update before exiting a heartbeat
Include this line verbatim for any execution-heavy role:
> Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
### 4. Domain lenses
5 to 15 named lenses the agent applies when making judgment calls. Lenses are short labels with a one-line explanation. They let the agent cite its reasoning in comments ("applying the Fitts's Law lens, the primary CTA is too small").
Lenses should be specific to the role. Examples of what good lenses look like:
- **UX designer**: Nielsen's 10, Gestalt proximity, Fitts's Law, Jakob's Law, Tesler's Law, Recognition over Recall, Kano Model, WCAG POUR.
- **Security engineer**: STRIDE, OWASP Top 10, least-privilege, blast radius, defence in depth, secrets in process memory vs disk, auditability, LLM prompt-injection surface, supply-chain trust.
- **Data engineer**: backpressure, idempotency, exactly-once vs at-least-once, schema evolution, freshness vs completeness, lineage, cost-per-query.
- **Ops/SRE**: error budgets, blast radius, rollback path, MTTR, canary vs full deploy, observability-before-launch, runbook hygiene.
- **Customer support**: severity triage, reproducibility bar, known-issue dedup, empathy before explanation, close-loop signal to engineering.
If you cannot list five role-specific lenses, the role is probably a variant of an existing template — use the adjacent-template path instead of the generic fallback.
### 5. Output / review bar
Describe what a good deliverable from this role looks like. Be concrete — give the bar a stranger could judge against:
- what shape the output takes (PR, spec, report, ticket triage, screenshot bundle)
- what it must include (repro steps, evidence, tradeoffs, acceptance criteria, sign-off from X)
- what "not done" looks like (e.g., "a flow that works but looks unstyled is not done")
- what never ships (e.g., "no secrets in plain text", "no deploys without a rollback path")
### 6. Collaboration and handoffs
Name the other agents or roles this agent must route to, and when:
- UX-facing changes → involve `[UXDesigner](/PAP/agents/uxdesigner)`
- security-sensitive changes, permissions, secrets, auth, adapter/tool access → involve `[SecurityEngineer](/PAP/agents/securityengineer)`
- browser validation / user-facing workflow verification → involve `[QA](/PAP/agents/qa)`
- skill architecture / instruction quality → involve the Skill Consultant
- engineering/runtime changes → involve CTO and a coder
Only list routes that apply to this role. Do not force every agent to CC the board.
### 7. Safety and permissions
Default to least privilege. For each new role, explicitly state:
- what the role is allowed to do that other agents cannot
- what the role must never do (examples: post to external services, modify shared infra, delete data without approval)
- how credentials/secrets are handled (never in plain text unless the adapter requires it; use `desiredSkills` or environment-injected credentials)
- whether a timer heartbeat is needed (default: off; only enable with an explicit justification and `intervalSec`)
- which `desiredSkills` the role needs on day one — install missing skills before submitting the hire
### 8. Done criteria
How the agent verifies its own work before marking an issue done or handing it to a reviewer. Be concrete:
- the smallest check that proves the work (tests run, screenshots captured, query executed, spec reviewed)
- what evidence goes in the final comment
- who the task is reassigned to on completion (reviewer, manager, or `done`)
---
## Anti-patterns to avoid
- **Over-generic prompts.** "Be helpful, be thorough, be correct" is worthless — the next agent drafts a better version by reading the template you adapted from. Write role-specific guidance only.
- **Lens dumping.** Copying every lens from an expert template into an unrelated role adds noise and burns context. Five well-chosen lenses beat fifteen irrelevant ones.
- **Permission sprawl.** Do not grant write access, admin endpoints, or broad skill sets "just in case." Grant exactly what the role needs.
- **Silent timer heartbeats.** A timer heartbeat burns budget every interval. If the role has no scheduled work, leave it off.
- **Bypassing governance.** Never skip `sourceIssueId`, reporting line, icon, or approval flow to ship faster. Hires without these are hard to audit and hard to hand off.
- **Copying another company's prompt verbatim.** Placeholders like `{{companyName}}`, `{{managerTitle}}`, and `{{issuePrefix}}` must be replaced with this company's values before submitting the hire.
---
## Minimal scaffold
Copy this scaffold into your draft and fill each section. Delete the comments (`<!-- -->`) once each section is specific.
```md
You are agent {{agentName}} ({{roleTitle}}) at {{companyName}}.
When you wake up, follow the Paperclip skill. It contains the full heartbeat procedure.
You report to {{managerTitle}}. Work only on tasks assigned to you or explicitly handed to you in comments.
## Role
<!-- One paragraph + bullets: what this agent owns, what it declines/escalates. -->
## Working rules
<!-- Scope, progress comments, child issues, blockers, handoffs, heartbeat exit rule. -->
## Domain lenses
<!-- 5-15 named lenses that guide judgment for this role. Cite by name in comments. -->
## Output bar
<!-- What a good deliverable looks like. Include concrete negative examples. -->
## Collaboration
<!-- Which agents to route to and when. -->
## Safety and permissions
<!-- Least privilege. Heartbeat default off. Secrets handling. desiredSkills. -->
## Done
<!-- How you verify before marking done. What evidence goes in the final comment. -->
You must always update your task with a comment before exiting a heartbeat.
```

91
skills/paperclip-create-agent/references/draft-review-checklist.md Normal file
View File

@@ -0,0 +1,91 @@
# Draft-Review Checklist
Walk this checklist before submitting any `agent-hires` request. Fix each item that does not pass — do not submit a draft with open failures.
Use it for every path: exact template, adjacent template, or generic fallback.
---
## A. Identity and framing
- [ ] `name`, `role`, and `title` are set and consistent with each other
- [ ] `AGENTS.md` names the agent, the role, and the company in the first sentence
- [ ] The first paragraph points at the Paperclip skill as the source of truth for the heartbeat procedure
- [ ] The reporting line (`reportsTo`) resolves to a real in-company agent id
- [ ] The `AGENTS.md` states the same reporting line in prose
## B. Role clarity
- [ ] `capabilities` is one concrete sentence about what the agent does — not a vague "assists with X"
- [ ] The role charter in `AGENTS.md` names what the agent owns end-to-end
- [ ] The charter names what the agent should decline, hand off, or escalate
- [ ] A stranger reading `capabilities` plus the role charter can tell in 30 seconds what this agent is for
## C. Operating workflow
- [ ] `AGENTS.md` states the comment-on-every-touch rule
- [ ] `AGENTS.md` states the "leave a clear next action" rule
- [ ] `AGENTS.md` covers how to mark work `blocked` with owner + action
- [ ] `AGENTS.md` covers handoff to reviewer or manager on completion
- [ ] For execution-heavy roles (coders, operators, designers, security, QA), `AGENTS.md` includes the Paperclip execution contract verbatim:
> Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
## D. Domain lenses and judgment
- [ ] Expert roles list 5–15 named lenses with one-line explanations
- [ ] Lenses are role-specific, not generic productivity advice
- [ ] Simple operational roles do not carry copy-pasted lenses from expert templates
## E. Output / review bar
- [ ] `AGENTS.md` describes what a good deliverable looks like for this role
- [ ] Negative examples are included where useful ("a flow that works but looks unstyled is not done")
- [ ] Evidence expectations are concrete (tests, screenshots, repro steps, spec sections)
## F. Collaboration routing
- [ ] Cross-role handoffs are named only when the role actually touches that domain
- [ ] UX-facing role or change → routes to `[UXDesigner](/PAP/agents/uxdesigner)`
- [ ] Security-sensitive role, permissions, secrets, auth, adapters, tool access → routes to `[SecurityEngineer](/PAP/agents/securityengineer)`
- [ ] Browser validation or user-facing verification → routes to `[QA](/PAP/agents/qa)`
- [ ] Skill architecture / instruction quality changes → routes to the Skill Consultant when present
- [ ] Engineering/runtime changes → routes to CTO and a coder
## G. Governance fields
- [ ] `icon` is set to one of `/llms/agent-icons.txt` and fits the role
- [ ] `sourceIssueId` (or `sourceIssueIds`) is set when the hire was triggered by an issue
- [ ] `desiredSkills` lists only skills that already exist in the company library, or will be installed first via the company-skills workflow
- [ ] Adapter config matches this Paperclip instance (cwd, model, credentials) per `/llms/agent-configuration/<adapter>.txt`
- [ ] `adapterConfig.promptTemplate` holds the adapted `AGENTS.md` for local managed-bundle adapters (unless you are intentionally managing bundle paths)
- [ ] Placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and any URL stubs are replaced with real values
## H. Safety and permissions (least privilege)
- [ ] The hire grants only the access the role needs — no "just in case" permissions
- [ ] No secrets are embedded in plain text in `adapterConfig` or `promptTemplate` unless the adapter explicitly requires it; prefer environment-injected credentials or scoped skills
- [ ] `runtimeConfig.heartbeat.enabled` is `false` unless the role genuinely needs scheduled recurring work AND `intervalSec` is justified in the hire comment
- [ ] `AGENTS.md` explicitly names anything the role must never do (external posts, shared infra changes, destructive ops without approval)
- [ ] No tool, skill, or capability is listed that this environment cannot actually provide
## I. Done criteria
- [ ] `AGENTS.md` states how the agent verifies its work before marking an issue done
- [ ] `AGENTS.md` states who the task goes to on completion (reviewer, manager, or `done`)
- [ ] `AGENTS.md` ends with the "always update your task with a comment" rule
## J. Choice of instruction source was explicit
- [ ] The hire comment states which path was used: exact template, adjacent template, or generic fallback
- [ ] If an adjacent template was used, the comment names what was adapted (charter rewritten, lenses swapped, sections removed)
- [ ] If the generic fallback was used, every section of the baseline role guide is present in the draft
---
## Failure modes to watch for
- **Boilerplate pass-through.** If `AGENTS.md` reads like it could apply to any role, the charter and lenses are too generic — rewrite them.
- **Quiet permission sprawl.** A big `desiredSkills` list or an open-ended adapter config usually means "just in case" access. Trim to what the charter needs.
- **Timer-heartbeat-by-default.** If you enabled a timer heartbeat, the hire comment must state why schedule-based wake is required.
- **Missing governance fields.** A hire without `sourceIssueId`, `icon`, or a resolvable reporting line is hard to audit later.
- **Unreplaced placeholders.** `{{companyName}}`, `{{managerTitle}}`, and URL stubs in a submitted draft are the most common rejected-hire defect — grep the draft for `{{` before submitting.