Clarify SDD guardrails against background Task usage

[stablegenius49]

Summary

• strengthen subagent-driven-development core principle to require strictly sequential dispatch
• replace the parallelism red flag with explicit prohibition on run_in_background + TaskOutput result retrieval
• add rationale explaining that background retrieval can return truncated transcript fragments and break review gates

Validation

• git diff --check
• verified updated guardrail text is present in skills/subagent-driven-development/SKILL.md

Fixes #485

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the subagent-driven-development skill documentation to emphasize strictly sequential task dispatch without background execution. Added clarification about why parallel dispatch is problematic, citing transcript truncation risks and disrupted review gates.

Changes

Cohort / File(s)	Summary
Skill Documentation Update skills/subagent-driven-development/SKILL.md	Core principle and Red Flags sections revised to explicitly mandate sequential dispatch (one task at a time) and discourage run_in_background or TaskOutput usage, with rationale about potential transcript corruption and invalidated review mechanisms.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 One task, then the next, in orderly line,
No rushing ahead, keep the sequence divine!
Sequential steps make the transcripts stay clean,
And reviewers can trust what they're seeing between.
Line by line, clear and bright, no tangled skein! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Clarify SDD guardrails against background Task usage' directly describes the main change: clarifying documentation to prohibit background task usage in subagent-driven development.
Description check	✅ Passed	The description is clearly related to the changeset, explaining the strengthened core principle, the replacement of the parallelism red flag, and the added rationale for background task prohibition.
Linked Issues check	✅ Passed	The PR fully addresses all coding-related requirements from issue #485: documenting strict sequential dispatch, prohibiting run_in_background with TaskOutput, and explaining the rationale about truncated transcripts and broken review gates.
Out of Scope Changes check	✅ Passed	All changes are scoped to the SKILL.md file and directly address the requirements from issue #485; no out-of-scope modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

skills/subagent-driven-development/SKILL.md (2)

10-10: Core principle update is clear, but verify consistency with line 172.

The addition of "strictly sequential dispatch (no background tasks)" clearly establishes the execution model. However, line 172 states "Parallel-safe (subagents don't interfere)" under advantages, which could be interpreted as conflicting with this prohibition.

Consider clarifying line 172 to specify that "parallel-safe" means multiple independent SDD workflows can run concurrently (e.g., different features), not that subagents within a single workflow run in parallel.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/subagent-driven-development/SKILL.md` at line 10, The wording is
potentially inconsistent: the new core principle adds "strictly sequential
dispatch (no background tasks)" while the advantages section still says
"Parallel-safe (subagents don't interfere)"; update the advantage phrase (the
text "Parallel-safe (subagents don't interfere)" on line with identifier
"Parallel-safe") to clarify that parallel-safe refers to running separate SDD
workflows concurrently (e.g., different features) rather than parallel execution
of subagents within a single workflow—adjust the sentence to explicitly state
"Parallel-safe: independent SDD workflows can run concurrently; subagents within
a single workflow are executed strictly sequentially" so the two statements are
consistent.

---

205-205: Clarify scope: does "implementation subagent" include reviewers?

The term "implementation subagent" is ambiguous. Given that the workflow includes three types of subagents (implementer, spec reviewer, code quality reviewer), and the rationale mentions "break review gates," it's unclear whether this prohibition applies to:

1. Only the implementer subagent (who writes code), or
2. All subagents in the SDD workflow (implementer + both reviewers)

If background dispatch of reviewers could also return truncated transcripts and break gates, consider either:

• Using "implementation or review subagent" or "any SDD subagent", or
• Explicitly listing all three subagent types

This would eliminate ambiguity and prevent models from assuming reviewers can be dispatched in background.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/subagent-driven-development/SKILL.md` at line 205, The phrase
"implementation subagent" in the line "Dispatch any implementation subagent with
`run_in_background: true` or retrieve results via `TaskOutput`" is ambiguous
about whether reviewers are included; update the wording to explicitly cover
scope by either renaming it to "implementation or review subagent" or "any SDD
subagent", or by listing the three subagent types (implementer, spec reviewer,
code quality reviewer) so it's clear reviewers must not be dispatched in
background unless intended.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skills/subagent-driven-development/SKILL.md`:
- Line 10: The wording is potentially inconsistent: the new core principle adds
"strictly sequential dispatch (no background tasks)" while the advantages
section still says "Parallel-safe (subagents don't interfere)"; update the
advantage phrase (the text "Parallel-safe (subagents don't interfere)" on line
with identifier "Parallel-safe") to clarify that parallel-safe refers to running
separate SDD workflows concurrently (e.g., different features) rather than
parallel execution of subagents within a single workflow—adjust the sentence to
explicitly state "Parallel-safe: independent SDD workflows can run concurrently;
subagents within a single workflow are executed strictly sequentially" so the
two statements are consistent.
- Line 205: The phrase "implementation subagent" in the line "Dispatch any
implementation subagent with `run_in_background: true` or retrieve results via
`TaskOutput`" is ambiguous about whether reviewers are included; update the
wording to explicitly cover scope by either renaming it to "implementation or
review subagent" or "any SDD subagent", or by listing the three subagent types
(implementer, spec reviewer, code quality reviewer) so it's clear reviewers must
not be dispatched in background unless intended.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 1719dc2c-5cf0-4d2f-bff0-a1707eb05518

📥 Commits

Reviewing files that changed from the base of the PR and between e4a2375 and e59d297.

📒 Files selected for processing (1)

• skills/subagent-driven-development/SKILL.md