From c96296a30e3f712561b5f05f3f1e9d95588f643e Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 19 Apr 2026 17:23:37 -0500
Subject: feat(rules): add subagents.md — when, how, and when not to delegate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cross-cutting rule covering subagent hygiene:

- Decision table: parallel-safe (read-only investigation, independent
  test failures, multi-domain research) vs sequential-with-review
  (plan execution, coupled edits) vs never-parallel (concurrent writes)
  vs don't-subagent-at-all (target known, work fits in ~10 tool calls).
- Prompt contract: scope / pasted context / explicit 'do NOT' list /
  required output format. Missing any field yields shallow work.
- Context-pollution rule: subagents absorb noise the main thread
  shouldn't carry. When one fails, dispatch a fix-agent with the
  failure report — do not retry in the orchestrator.
- Review-gate cadence: after each sequential task, or every ~3 in
  parallel batches.
- Anti-patterns including parallel implementation on overlapping
  files, broad 'fix all the tests' prompts, timeout-tuning to mask
  flakes, and letting the agent decide scope.

Added one-line cross-references to subagents.md from debug/,
review-code/, and finish-branch/ SKILL.md — the skills that most
rely on delegation.

Clean-room synthesis from NeoLabHQ/context-engineering-kit's
subagent-driven-development pattern (MIT).
---
 debug/SKILL.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'debug/SKILL.md')

diff --git a/debug/SKILL.md b/debug/SKILL.md
index e4e1041..7f3771a 100644
--- a/debug/SKILL.md
+++ b/debug/SKILL.md
@@ -46,6 +46,8 @@ Do not propose any fix during this phase. You are gathering evidence.
 
 If you've attempted 3 fixes and the bug persists, stop. The problem is likely architectural, not local. Report what you've learned and recommend a broader investigation rather than attempting fix #4.
 
+When fanning out investigation across multiple independent files or subsystems, follow `subagents.md` — use parallel read-only agents for exploration, never for concurrent writes, and dispatch a fresh fix-agent on failure rather than retrying in the main context.
+
 ## What Not to Do
 
 - Don't propose fixes before completing Phase 2
-- 
cgit v1.2.3