Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: add guide for handling complex features (#3004)

Manfred Riem860a49edb1eb
diff --git a/docs/concepts/complex-features.md b/docs/concepts/complex-features.md
new file mode 100644
index 000000000..10e814ba1
--- /dev/null
+++ b/docs/concepts/complex-features.md
@@ -0,0 +1,83 @@
+# Handling Complex Features
+
+Large or complex features often run smoothly through `/speckit.specify`,
+`/speckit.plan`, and `/speckit.tasks`, then degrade during implementation. In
+the middle of a long `/speckit.implement` run, agents can start to lose track of
+the plan, ignore tasks, or hallucinate β€” usually right before or after context
+compaction is triggered.
+
+The underlying cause is context window exhaustion. When a single
+implementation run tries to hold the entire feature in context, the model
+degrades as the window fills. The fix is to scope each run so it stays well
+within context limits.
+
+The `/speckit.implement` command accepts free-form user input that the agent
+must consider before proceeding. This means you can scope each run without any
+tooling changes.
+
+## Option 1: Limit How Many Tasks Run Per Invocation
+
+Instead of letting `/speckit.implement` run through every task at once, tell it
+to stop early:
+
+```text
+/speckit.implement only execute tasks T001-T010, then stop and report progress
+```
+
+or scope by phase:
+
+```text
+/speckit.implement only execute the Setup phase, then stop
+```
+
+Because completed tasks are marked `[X]` in `tasks.md`, the next
+`/speckit.implement` invocation picks up where you left off. This keeps each run
+well within context limits.
+
+## Option 2: Instruct the Agent to Use Sub-Agents
+
+If your coding agent supports sub-agents (for example, GitHub Copilot CLI or the
+GitHub Copilot extension for VS Code), you can instruct `/speckit.implement` to
+delegate individual tasks:
+
+```text
+/speckit.implement delegate each parallel [P] task to a sub-agent
+```
+
+Each sub-agent gets a focused context β€” one task plus the relevant plan
+excerpts β€” rather than the full feature context, so compaction never triggers
+in the main session.
+
+## Option 3: Combine Both
+
+For very large features, combine scoping and delegation:
+
+```text
+/speckit.implement execute only the Core phase, delegate [P] tasks to sub-agents
+```
+
+## Option 4: Decompose the Feature Into Smaller Specs
+
+When even a single phase overwhelms the context, break the feature into
+independently specified sub-features. Each sub-feature gets its own
+`spec.md`, `plan.md`, and `tasks.md`, and runs through its own
+specify/plan/tasks/implement cycle.
+
+This is the "spec of specs" approach: the first iteration breaks a massive
+feature into smaller, self-contained specs that can each be implemented without
+overwhelming the model. It adds the most overhead, so reserve it for features
+that are too large to handle any other way.
+
+## Which Approach to Choose
+
+| Approach | Best for |
+| --- | --- |
+| Limit to N tasks or a phase | Any agent; simplest; no sub-agent support needed |
+| Sub-agent delegation | Agents that support sub-agents; maximizes parallelism |
+| Combine scoping + delegation | Large features on sub-agent-capable agents; balances both |
+| Decompose into smaller specs | When even a single phase overwhelms the context |
+
+For most cases, limiting task scope per run is the simplest fix. Reach for
+sub-agent delegation when your agent supports it and you want parallelism, and
+decompose into smaller specs only when a single phase is still too large to
+handle in one run.
diff --git a/docs/toc.yml b/docs/toc.yml
index e5fb07fbb..250120612 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -43,6 +43,8 @@
href: concepts/sdd.md
- name: Spec Persistence Models
href: concepts/spec-persistence.md
+ - name: Handling Complex Features
+ href: concepts/complex-features.md
# Development workflows
- name: Development