From d996bfde48e39f851523d797e0910b864fe3b1e3 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 9 May 2026 15:34:58 -0700 Subject: [PATCH 1/4] agents|fix: Recommend direct implementation for bounded changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After producing an implementation plan, the next-steps menu now recommends direct implementation for single-module or single-package work whose consequences fit a single end-of-work review pass. Previously, the recommendation rule admitted only trivial or mechanical work, leaving common right-fit patterns — precise plans for bounded changes — to default to orchestration. The framing leak in option 3's description has been removed. The previous text positioned direct implementation as a worse-quality path ("no review cycle"); the description cell is now empty since option 3 is self-explanatory. Companion surfaces (the complexity-classification consumer threshold and the refine-plan post-revision hint) now match the broadened framing rather than pre-biasing toward orchestration. --- .../skills/_data/complexity-classification.md | 12 ++++++------ .../content/skills/_data/next-steps-after-plan.md | 12 ++++++------ packages/agents/content/skills/refine-plan/SKILL.md | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/packages/agents/content/skills/_data/complexity-classification.md b/packages/agents/content/skills/_data/complexity-classification.md index d4f2d7c5..80e4f113 100644 --- a/packages/agents/content/skills/_data/complexity-classification.md +++ b/packages/agents/content/skills/_data/complexity-classification.md @@ -43,12 +43,12 @@ Classify the complexity of a task, finding, or change to determine how it should Each consuming skill defines its own threshold against this rubric. The threshold indicates which levels qualify for the consumer's "simple enough" decision. -| Consumer | Threshold | Decision | -| ---------------------------------- | --------- | ------------------------------------------------------------------ | -| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | -| `next-steps-after-plan` | 1–2 | Recommend "implement directly" (no orchestration needed) | -| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix) | -| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | +| Consumer | Threshold | Decision | +| ---------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | +| `next-steps-after-plan` | 1–2 | Recommend "Implement directly"; rule 2 broadens beyond strict levels 1–2 when the verification surface fits a single review pass | +| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix) | +| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | When characteristics span two levels, prefer the higher level. This is consistent with the "when uncertain, recommend the more thorough option" pattern used by consuming skills. diff --git a/packages/agents/content/skills/_data/next-steps-after-plan.md b/packages/agents/content/skills/_data/next-steps-after-plan.md index 01b24b4c..690fca70 100644 --- a/packages/agents/content/skills/_data/next-steps-after-plan.md +++ b/packages/agents/content/skills/_data/next-steps-after-plan.md @@ -4,11 +4,11 @@ Standard next-steps block for skills that produce or refine an implementation pl ## Options -| # | Emoji | Option | Description | -| --- | ----- | ------------------ | ------------------------------------------------- | -| 1 | 🧠 | Refine plan | Review the plan for completeness and correctness | -| 2 | 🎶 | Orchestrate | Run the full orchestrated development pipeline | -| 3 | 🚀 | Implement directly | Implement without orchestration (no review cycle) | +| # | Emoji | Option | Description | +| --- | ----- | ------------------ | ------------------------------------------------ | +| 1 | 🧠 | Refine plan | Review the plan for completeness and correctness | +| 2 | 🎶 | Orchestrate | Run the full orchestrated development pipeline | +| 3 | 🚀 | Implement directly | | ## Output format @@ -57,7 +57,7 @@ Select the recommended option by checking these rules in order and stopping at t - The plan has not been previously refined - A prior iteration of `refine-plan` resulted in significant alteration of the plan or significant expansion of the scope of the changes required to implement the plan -2. **Implement directly** — recommend when the work falls at [complexity levels 1–2](complexity-classification.md) (trivial or mechanical — e.g., single module, no cross-cutting renames or shared convention changes), or follows an established pattern closely enough that the coder's first pass is sufficient +2. **Implement directly** — recommend when the work's verification surface fits a single end-of-work review pass: single module/package, the plan is precise (or follows an established pattern closely), and the implementation's consequences are bounded enough that compiler + tests + one review pass would catch the meaningful classes of mistake. Cross-cutting changes, novel patterns, or work whose consequences ripple beyond the immediate change site fall through to rule 3. 3. **Orchestrate** — all other cases (default) Each skill supplies its own recommendation context (e.g., whether the plan was developed interactively, whether a review just completed). Apply these rules using that context. diff --git a/packages/agents/content/skills/refine-plan/SKILL.md b/packages/agents/content/skills/refine-plan/SKILL.md index 7d8327af..272881ff 100644 --- a/packages/agents/content/skills/refine-plan/SKILL.md +++ b/packages/agents/content/skills/refine-plan/SKILL.md @@ -211,7 +211,7 @@ Plan refined: ``` -Read [next-steps-after-plan](../_data/next-steps-after-plan.md) and follow its options, output format, and recommendation rules exactly. Do not improvise the options. The plan was just reviewed. If the review surfaced significant scope changes or unresolved questions that led to a dramatic revision, the plan may warrant another refinement round; otherwise, orchestration is the typical recommendation. Use this as recommendation context. Include both `{revision_output_path}` (as the plan path) and `{ticket_source}` in each skill-invoking option line. +Read [next-steps-after-plan](../_data/next-steps-after-plan.md) and follow its options, output format, and recommendation rules exactly. Do not improvise the options. The plan was just reviewed. If the review surfaced significant scope changes or unresolved questions that led to a dramatic revision, the plan may warrant another refinement round; otherwise, either orchestration or direct implementation may apply depending on whether the work's consequences fit a single review pass. Use this as recommendation context. Include both `{revision_output_path}` (as the plan path) and `{ticket_source}` in each skill-invoking option line. ## Edge cases From 2b6d0c81bbd336ac56788ae3230ea9db3f658491 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 9 May 2026 15:45:40 -0700 Subject: [PATCH 2/4] agents|fix: Determine need for review in next-steps threshold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The complexity-classification consumer-threshold row for `next-steps-after-plan` now distinguishes two cases. Simple (trivial and mechanical changes) get a plain "Implement directly" recommendation, since a follow-up review pass would catch nothing meaningful. Other work whose verification surface still fits a single review pass gets "Implement directly with follow-up review" — pairing the implementation with a review pass adds value when the work is broader than trivial but bounded enough that one review pass covers it. --- .../skills/_data/complexity-classification.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/agents/content/skills/_data/complexity-classification.md b/packages/agents/content/skills/_data/complexity-classification.md index 80e4f113..9195cc73 100644 --- a/packages/agents/content/skills/_data/complexity-classification.md +++ b/packages/agents/content/skills/_data/complexity-classification.md @@ -11,28 +11,28 @@ Classify the complexity of a task, finding, or change to determine how it should | 3 | **Involved** | Requires understanding context. Touches multiple files or modules. May involve design decisions. | | 4 | **Architectural** | Cross-cutting concerns, new patterns, dependency boundary changes, or far-reaching consequences. | -### Level 1 — trivial +### Level 1: Trivial - Remove unused import - Fix typo in error message or variable name - Add missing return type that the compiler can infer - Delete dead code already flagged by a linter -### Level 2 — mechanical +### Level 2: Mechanical - Rename a local function or variable across its usages within a single module - Add a missing test case that follows an existing test pattern - Extract a repeated literal into a named constant - Update a reference path after a file was moved -### Level 3 — involved +### Level 3: Involved - Refactor retry logic to use a shared utility - Add error handling for a new edge case that requires understanding the call chain - Modify a data structure shared between modules - Implement a feature that follows an established pattern but spans multiple files -### Level 4 — architectural +### Level 4: Architectural - Introduce a new subsystem or module boundary - Change how modules communicate (new interfaces, events, or protocols) @@ -43,12 +43,12 @@ Classify the complexity of a task, finding, or change to determine how it should Each consuming skill defines its own threshold against this rubric. The threshold indicates which levels qualify for the consumer's "simple enough" decision. -| Consumer | Threshold | Decision | -| ---------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | -| `next-steps-after-plan` | 1–2 | Recommend "Implement directly"; rule 2 broadens beyond strict levels 1–2 when the verification surface fits a single review pass | -| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix) | -| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | +| Consumer | Threshold | Decision | +| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | +| `next-steps-after-plan` | 1–2 | For changes that would not benefit from review, recommend "Implement directly". For work where the verification surface fits a single review pass, recommend "Implement directly with follow-up review" (rule 2's broader criterion). | +| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix without further review) | +| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | When characteristics span two levels, prefer the higher level. This is consistent with the "when uncertain, recommend the more thorough option" pattern used by consuming skills. From 08c74c3b4325d3d58d231963c9f600ed932086c1 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 9 May 2026 16:04:15 -0700 Subject: [PATCH 3/4] agents|refactor: Rename 'Threshold' column to 'Levels' for accuracy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Threshold" column header in the consumer-thresholds table connoted a single boundary value, but the column holds level ranges (e.g., 1–2). Rename the column and surrounding prose to use "Levels," which matches what the column actually contains. The section header changes accordingly, and the trailing-paragraph reference to "mapping mechanically to a single threshold" is reworded to "relying solely on this table." --- .../skills/_data/complexity-classification.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/agents/content/skills/_data/complexity-classification.md b/packages/agents/content/skills/_data/complexity-classification.md index 9195cc73..996482a0 100644 --- a/packages/agents/content/skills/_data/complexity-classification.md +++ b/packages/agents/content/skills/_data/complexity-classification.md @@ -39,19 +39,19 @@ Classify the complexity of a task, finding, or change to determine how it should - Modify dependency boundaries (add/remove/replace libraries) - Restructure control flow or state management across components -## Consumer thresholds +## Consumer levels -Each consuming skill defines its own threshold against this rubric. The threshold indicates which levels qualify for the consumer's "simple enough" decision. +Each consuming skill defines which complexity levels qualify for its "simple enough" decision against this rubric. -| Consumer | Threshold | Decision | -| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | -| `next-steps-after-plan` | 1–2 | For changes that would not benefit from review, recommend "Implement directly". For work where the verification surface fits a single review pass, recommend "Implement directly with follow-up review" (rule 2's broader criterion). | -| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix without further review) | -| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | +| Consumer | Levels | Decision | +| ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | +| `next-steps-after-plan` | 1–2 | For changes that would not benefit from review, recommend "Implement directly". For work where the verification surface fits a single review pass, recommend "Implement directly with follow-up review" (rule 2's broader criterion). | +| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix without further review) | +| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | When characteristics span two levels, prefer the higher level. This is consistent with the "when uncertain, recommend the more thorough option" pattern used by consuming skills. -Consumers above level 2 should use the level descriptions to inform their own routing logic rather than mapping mechanically to a single threshold. +Consumers above level 2 should use the level descriptions to inform their own routing logic rather than relying solely on this table. The complexity rubric and the [ticket-creation-cost](ticket-creation-cost.md) model compose: complexity drives orchestration-routing decisions (which skill picks the work up next), while ticket-creation-cost drives ticket-creation decisions (whether the work needs its own ticket at all). From 70a961d4f4ee6830e9b371507591f558799833a0 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 9 May 2026 16:17:53 -0700 Subject: [PATCH 4/4] agents|fix: Make next-steps consumer-levels cell partition cleanly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The decision cell for `next-steps-after-plan` previously stated two conditions ("would not benefit from review" and "verification surface fits a single review pass") as if they partitioned the space, but they did not — the conditions overlapped and left edge cases ambiguous. They also overloaded the word "trivial," which is reserved as the Level-1 rubric label. The cell now defaults to "Implement directly with follow-up review" and carves out a single exception for cases where a review pass would catch nothing meaningful. --- .../skills/_data/complexity-classification.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/agents/content/skills/_data/complexity-classification.md b/packages/agents/content/skills/_data/complexity-classification.md index 996482a0..303b76b9 100644 --- a/packages/agents/content/skills/_data/complexity-classification.md +++ b/packages/agents/content/skills/_data/complexity-classification.md @@ -43,12 +43,12 @@ Classify the complexity of a task, finding, or change to determine how it should Each consuming skill defines which complexity levels qualify for its "simple enough" decision against this rubric. -| Consumer | Levels | Decision | -| ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | -| `next-steps-after-plan` | 1–2 | For changes that would not benefit from review, recommend "Implement directly". For work where the verification surface fits a single review pass, recommend "Implement directly with follow-up review" (rule 2's broader criterion). | -| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix without further review) | -| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | +| Consumer | Levels | Decision | +| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation | +| `next-steps-after-plan` | 1–2 | Recommend "Implement directly with follow-up review". When a review pass would catch nothing meaningful (e.g., a typo or unused-import removal), recommend "Implement directly" instead. | +| `next-steps-after-review` | 1–2 | Recommend "implement directly" (findings are simple enough to fix without further review) | +| `orchestrated-architect` (planned) | 1–2 | Classify as `none`/`low` impact (minimal architectural guidance) | When characteristics span two levels, prefer the higher level. This is consistent with the "when uncertain, recommend the more thorough option" pattern used by consuming skills.