forgejo-admin/herdrmastr
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Make brief composition a procedure in the spawn skill, not advice #2

Merged
forgejo-admin merged 1 commit from improve-spawn-brief-guidance into main 2026-07-31 19:41:15 +00:00
Conversation 0 Commits 1 Files changed 3 +98 -6
forgejo-admin commented 2026-07-31 19:38:24 +00:00
Owner
Copy link

Follow-up to #1, from thinking about how spawning actually gets triggered in practice.

The real trigger

The original skill was written for a cold start — as if the spawning agent would need to go learn about the target project. That's the rare case. The realistic one:

An agent is working. It finds a problem tangential to what the user actually cares about right now. It mentions it. The user says "spawn a new celilo agent to deal with that."

The agent already holds 100% of the context. It did the diagnosis. The risk was never that it lacks information — it's that it fails to transfer it.

Two failure modes the old wording didn't prevent

Passthrough — the user's one sentence becomes the brief:

spawn new celilo fix-e2e "Fix e2e tests" "e2e tests need to be fixed"

The spawned agent now has less context than the user gave the spawning agent, and it re-derives everything from scratch.

Deixis — "fix the failure above", "this bug", "what we discussed". The new agent starts with an empty conversation. Every one of those references is meaningless to it.

Changes

skill/SKILL.md — the advisory paragraph becomes a procedure:

  • Four rules: never pass the user's sentence through (if your brief is shorter than what the user said, you did it wrong); no deixis; dump the diagnosis you already did; state what "done" means and what's out of scope.
  • A brief skeleton — symptom / what I already know (with file:line, verbatim errors, what was ruled out) / where to start / done means / out of scope.
  • Rule 3 is the load-bearing one. Making the spawned agent rediscover what the spawning agent already knows is the most expensive mistake available, and the easiest to avoid — you're literally holding the answer while you write.
  • Cold-start guidance is kept, but demoted to the rarer case, and now says an investigation brief is a legitimate brief.

Confirmation is now conditional on the agent's own certainty, per operator preference: show the brief when you had to guess at something material; spawn straight through when you have the context cold. This keeps the one-liner path fast and puts the checkpoint exactly where the risk is.

Description trigger — added spawn a new <project> agent to deal with <thing>, since the project-as-adjective phrasing is how the request actually gets made.

README.md — one paragraph explaining to the operator why brief quality is the lever.

openspec/specs/agent-spawn-plugin/spec.md — the skill requirement now says brief composition must be a procedure, with three new scenarios covering passthrough, diagnosis transfer, and the conditional confirmation rule.

Verification

openspec validate --all 4/4 · spawn selftest ok

Docs and spec only — no behavior change to bin/spawn.

🤖 Generated with Claude Code

Follow-up to #1, from thinking about how spawning actually gets triggered in practice. ## The real trigger The original skill was written for a cold start — as if the spawning agent would need to go learn about the target project. That's the rare case. The realistic one: > An agent is working. It finds a problem tangential to what the user actually cares about right now. It mentions it. The user says *"spawn a new celilo agent to deal with that."* The agent already holds **100% of the context**. It did the diagnosis. The risk was never that it lacks information — it's that it fails to **transfer** it. ## Two failure modes the old wording didn't prevent **Passthrough** — the user's one sentence becomes the brief: ```sh spawn new celilo fix-e2e "Fix e2e tests" "e2e tests need to be fixed" ``` The spawned agent now has *less* context than the user gave the spawning agent, and it re-derives everything from scratch. **Deixis** — "fix the failure above", "this bug", "what we discussed". The new agent starts with an empty conversation. Every one of those references is meaningless to it. ## Changes `skill/SKILL.md` — the advisory paragraph becomes a procedure: - **Four rules**: never pass the user's sentence through (if your brief is shorter than what the user said, you did it wrong); no deixis; dump the diagnosis you already did; state what "done" means and what's out of scope. - **A brief skeleton** — symptom / what I already know (with `file:line`, verbatim errors, what was ruled out) / where to start / done means / out of scope. - **Rule 3 is the load-bearing one.** Making the spawned agent rediscover what the spawning agent already knows is the most expensive mistake available, and the easiest to avoid — you're literally holding the answer while you write. - Cold-start guidance is kept, but demoted to the rarer case, and now says an *investigation brief* is a legitimate brief. **Confirmation is now conditional on the agent's own certainty**, per operator preference: show the brief when you had to guess at something material; spawn straight through when you have the context cold. This keeps the one-liner path fast and puts the checkpoint exactly where the risk is. **Description trigger** — added `spawn a new <project> agent to deal with <thing>`, since the project-as-adjective phrasing is how the request actually gets made. `README.md` — one paragraph explaining to the operator why brief quality is the lever. `openspec/specs/agent-spawn-plugin/spec.md` — the skill requirement now says brief composition must be a procedure, with three new scenarios covering passthrough, diagnosis transfer, and the conditional confirmation rule. ## Verification `openspec validate --all` 4/4 · `spawn selftest` ok Docs and spec only — no behavior change to `bin/spawn`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
The realistic trigger is: an agent finds a problem tangential to what the user
is doing, mentions it, and the user says "spawn an agent for that." The agent
already holds the full context — the risk is not that it lacks information, it
is that it fails to transfer it.

Two failure modes the previous wording did not prevent:

- Passthrough. The user's one sentence becomes the brief, and the spawned agent
  starts with less context than the user gave the spawning agent.
- Deixis. "Fix the failure above" refers to a conversation the new agent was
  never in.

Replaces the advisory paragraph with four rules, a brief skeleton, and an
explicit instruction to dump diagnosis already performed (verbatim errors,
file:line, what was ruled out) rather than making the spawned agent rediscover
it. Cold-start guidance is kept but demoted to the rarer case it is.

Confirmation is now conditional on the spawning agent's own certainty: show the
brief when you had to guess, spawn straight through when you have the context
cold. Adds the "spawn a new <project> agent" phrasing to the skill description
so the project-as-adjective form triggers it.

Spec updated with three scenarios covering passthrough, diagnosis transfer, and
the conditional confirmation rule.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo-admin/herdrmastr!2
No description provided.