From 9d60c322ab31d7f1c3ea68b99f7f5f180764d885 Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Tue, 16 Jun 2026 10:22:16 -0500 Subject: [PATCH 1/3] docs: add guide for handling complex features Add a Concepts page documenting strategies for dealing with large or complex features where context window exhaustion degrades agent performance during implementation. Covers limiting tasks per run, sub-agent delegation, combining both, and decomposing into smaller specs, with a guideline table for choosing an approach. Closes #2986 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/concepts/complex-features.md | 81 +++++++++++++++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 83 insertions(+) create mode 100644 docs/concepts/complex-features.md diff --git a/docs/concepts/complex-features.md b/docs/concepts/complex-features.md new file mode 100644 index 0000000000..eda6fffed7 --- /dev/null +++ b/docs/concepts/complex-features.md @@ -0,0 +1,81 @@ +# 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 `implement` command accepts free-form user input that the agent is required +to honor 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 implement run through every task at once, tell it to stop +early: + +```text +/speckit.implement only execute tasks 1-10, 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, Copilot CLI or VS Code +Copilot), you can instruct 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 | +| 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 e5fb07fbba..2501206127 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 From 0cd4e0b12e7256c341ae53321aee54cb4dffc35a Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Tue, 16 Jun 2026 10:28:55 -0500 Subject: [PATCH 2/3] docs: address review feedback on complex features guide Use task IDs (T001-T010) instead of bare numbers to match the tasks.md template format, and add the combined scoping + delegation approach to the selection table for completeness. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/concepts/complex-features.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/concepts/complex-features.md b/docs/concepts/complex-features.md index eda6fffed7..cc9a6b5aaa 100644 --- a/docs/concepts/complex-features.md +++ b/docs/concepts/complex-features.md @@ -21,7 +21,7 @@ Instead of letting implement run through every task at once, tell it to stop early: ```text -/speckit.implement only execute tasks 1-10, then stop and report progress +/speckit.implement only execute tasks T001-T010, then stop and report progress ``` or scope by phase: @@ -73,6 +73,7 @@ that are too large to handle any other way. | --- | --- | | 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 From 54f42a53a221759f4363cba7dabb95adf0d2384b Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Tue, 16 Jun 2026 13:14:15 -0500 Subject: [PATCH 3/3] docs: align complex features guide with command naming conventions Use the full /speckit.implement command name throughout, match the command template wording ('must consider'), and use the product names GitHub Copilot CLI and the GitHub Copilot extension for VS Code. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/concepts/complex-features.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/concepts/complex-features.md b/docs/concepts/complex-features.md index cc9a6b5aaa..10e814ba12 100644 --- a/docs/concepts/complex-features.md +++ b/docs/concepts/complex-features.md @@ -11,14 +11,14 @@ 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 `implement` command accepts free-form user input that the agent is required -to honor before proceeding. This means you can scope each run without any +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 implement run through every task at once, tell it to stop -early: +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 @@ -36,8 +36,9 @@ well within context limits. ## Option 2: Instruct the Agent to Use Sub-Agents -If your coding agent supports sub-agents (for example, Copilot CLI or VS Code -Copilot), you can instruct implement to delegate individual tasks: +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