Private
Public Access
feat(directives): scavenge superpowers plugin (using-superpowers, brainstorming, dispatching-parallel-agents, executing-plans): 6 directives
This commit is contained in:
@@ -0,0 +1,8 @@
|
||||
# agent_prompt_one_independent_domain
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/dispatching-parallel-agents/SKILL.md`. The directive encodes the four Common Mistakes (broad scope, no context, no constraints, vague output) and the four required axes of a good agent prompt (focused, self-contained, specific output, constrained). Counterweight to the LLM default of "Fix all the tests in the suite" prompts that lose the sub-agent in scope.
|
||||
**Source:** superpowers plugin `skills/dispatching-parallel-agents/SKILL.md:86-90` (Good agent prompts) + `:113-122` (Common Mistakes table)
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,42 @@
|
||||
# Sub-agent prompts scope exactly ONE independent problem domain — "fix all the tests" is the canonical anti-pattern
|
||||
|
||||
## The rule
|
||||
|
||||
When dispatching a sub-agent for parallel or focused work, the agent prompt's scope is exactly one test file, one subsystem, or one independent problem. "Fix all the tests in the suite" or "investigate the bug across the codebase" is too broad; the agent gets lost in scope and the answer is shallow.
|
||||
|
||||
Per `skills/dispatching-parallel-agents/SKILL.md:113-122` (Common Mistakes):
|
||||
|
||||
> **❌ Too broad:** "Fix all the tests" - agent gets lost
|
||||
> **✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
|
||||
>
|
||||
> **❌ No context:** "Fix the race condition" - agent doesn't know where
|
||||
> **✅ Context:** Paste the error messages and test names
|
||||
>
|
||||
> **❌ No constraints:** Agent might refactor everything
|
||||
> **✅ Constraints:** "Do NOT change production code" or "Fix tests only"
|
||||
>
|
||||
> **❌ Vague output:** "Fix it" - you don't know what changed
|
||||
> **✅ Specific:** "Return summary of root cause and changes"
|
||||
|
||||
## The four axes of a good prompt
|
||||
|
||||
Every good agent prompt has all four (per `skills/dispatching-parallel-agents/SKILL.md:86-90` "Good agent prompts"):
|
||||
|
||||
1. **Focused** — one clear problem domain (one test file, one subsystem, one error)
|
||||
2. **Self-contained** — all context the agent needs to understand the problem is pasted in (error messages, file paths, test names, expected vs actual)
|
||||
3. **Specific about output** — what does the agent return? (a verdict, a diff summary, a root cause, an artifact)
|
||||
4. **Constrained** — what may the agent NOT touch? ("do not change production code"; "fix tests only")
|
||||
|
||||
## Why
|
||||
|
||||
A broad scope forces the sub-agent to triage on the orchestrator's behalf. The orchestrator already triaged — that is why this work is a single dispatch and not a brainstorming session. The sub-agent's job is execution, not scoping. Forcing it to scope blurs the boundary between orchestrator and worker, and the worker either makes bad scope decisions or returns a half-scoped answer.
|
||||
|
||||
Per the canonical anti-pattern from `skills/dispatching-parallel-agents/SKILL.md:113`: "**❌ Too broad:** 'Fix all the tests' - agent gets lost." The agent prompt's first sentence should name the file, the subsystem, or the failure domain.
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- A sub-agent prompt always begins with "Fix [specific file]" / "Investigate [specific subsystem]" / "Resolve [specific error]."
|
||||
- The prompt body pastes the relevant error messages, test names, and exact lines; the agent does not have to re-derive context.
|
||||
- The prompt explicitly enumerates what the agent must NOT change ("Do not modify production code in this dispatch; fix tests only").
|
||||
- The prompt's output section names the artifact shape ("Return: a 1-paragraph summary of root cause + the list of files changed"). The agent does not have to guess.
|
||||
- If the work needs to touch more than one independent domain, dispatch separate agents for each; do not bundle them.
|
||||
Reference in New Issue
Block a user