#306 Add shared complexity rubric and quick-fix pass to wrap-up

packages/agents/content/skills/_data/complexity-classification.md

@@ -0,0 +1,55 @@
+# Complexity classification
+
+Classify the complexity of a task, finding, or change to determine how it should be handled. Skills reference this rubric to make consistent routing and triage decisions.
+
+## Levels
+
+| Level | Label             | Characteristics                                                                                                   |
+| ----- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 1     | **Trivial**       | Single-line or purely mechanical. No judgment needed. The fix is obvious from the description alone.              |
+| 2     | **Mechanical**    | Follows an obvious pattern. Single module, no API or behavioral changes. A competent agent's first pass suffices. |
+| 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
+
+- 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
+
+- 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
+
+- 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
+
+- Introduce a new subsystem or module boundary
+- Change how modules communicate (new interfaces, events, or protocols)
+- Modify dependency boundaries (add/remove/replace libraries)
+- Restructure control flow or state management across components
+
+## Consumer thresholds
+
+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` quick-fix pass           | 1–2       | Apply immediately; 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)   |
+
+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.

packages/agents/content/skills/_data/next-steps-after-plan.md

@@ -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 is mechanical and isolated (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 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
 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.

packages/agents/content/skills/_data/next-steps-after-review.md

@@ -76,11 +76,11 @@ Skill names for each option:
 
 Select the recommended option using these rules in priority order:
 
-1. **Design and plan** -- findings suggest the approach needs rethinking (e.g., architectural issues, fundamental design problems, multiple FIXMEs that point to a flawed strategy)
-2. **Orchestrate** -- findings are non-trivial but the approach is sound (e.g., a mix of warnings and TODOs, or FIXMEs that are localized fixes)
-3. **Implement directly** -- findings are simple and well-understood (e.g., a few TODOs, minor warnings with obvious fixes)
+1. **Design and plan** -- findings suggest the approach needs rethinking — [complexity level 4](complexity-classification.md) (e.g., architectural issues, fundamental design problems, multiple FIXMEs that point to a flawed strategy)
+2. **Orchestrate** -- findings are non-trivial but the approach is sound — [complexity level 3](complexity-classification.md) (e.g., a mix of warnings and TODOs, or FIXMEs that are localized fixes)
+3. **Implement directly** -- findings fall at [complexity levels 1–2](complexity-classification.md) (e.g., a few TODOs, minor warnings with obvious fixes)
 
-When uncertain between two options, recommend the more thorough one.
+Complexity levels classify individual findings, but the recommendation applies to the collection. Multiple low-level findings that together indicate a design flaw may warrant a higher recommendation than any single finding's level suggests. When uncertain between two options, recommend the more thorough one.
 
 Each skill supplies its own recommendation context (e.g., finding counts and categories, severity of deviations). Apply these rules using that context.
 

packages/agents/content/skills/wrap-up/SKILL.md

@@ -87,6 +87,14 @@ For each deferred item found, assign a prefix from the item vocabulary based on
 
 Record the source attribution for each item (e.g., "run-summary", "holistic review", "conversation").
 
+#### 1b-iii. Assess complexity
+
+For each finding (not legacy items or insights), assess its complexity using the [complexity classification](../_data/complexity-classification.md) rubric. Assign a level (1–4) based on the characteristics described in the rubric.
+
+Items at levels 1–2 (trivial or mechanical) are **quick-fix candidates** — simple enough for the agent to apply immediately without review. Tag these items for the quick-fix pass in Phase 2a.
+
+Items at levels 3–4 remain in the standard findings pool for the housekeeping menu in Phase 2b.
+
 #### 1c. Scan for insights
 
 Insights are notable observations worth preserving — patterns learned, surprising findings, or knowledge that would benefit future work.
@@ -116,9 +124,35 @@ Run `git status` and `git log --oneline {default_branch}..HEAD` to understand:
 - How many commits are on the branch?
 - Has a change summary already been generated? (Check for `*_change-summary.md` artifacts.)
 
-### Phase 2: Inventory and action menu
+### Phase 2a: Quick fixes
 
-Present the user with an inventory of addressable items and a numbered action menu. Only include sections that have at least one item.
+If any findings were tagged as quick-fix candidates (complexity levels 1–2) in step 1b-iii, present them for immediate action before the housekeeping menu. Skip this phase entirely if no items qualify — do not show an empty section.
+
+#### Output format
+
+```
+### Quick fixes
+
+These findings are simple enough to apply now:
+
+  {prefix} {ID}    {description}
+
+  {prefix} {ID}    {description}
+
+Apply quick fixes? Reply "all", numbers, or "skip"
+```
+
+#### Response handling
+
+- **Applied items**: make the changes and commit them with a message summarizing the fixes. Stage only the quick-fix changes — if uncommitted work from earlier in the session exists, keep it separate. Remove applied items from the findings pool. They do not appear in Phase 2b.
+- **Skipped items**: demote back into the Findings section. They become eligible for the "Create tickets for findings" action in Phase 2b.
+- **Partial selection** (e.g., `"1, 3"`): apply selected items, demote the rest.
+
+**Wait for the user to respond before proceeding.**
+
+### Phase 2b: Inventory and action menu
+
+Present the user with an inventory of remaining addressable items and a numbered action menu. Only include sections that have at least one item. Items applied as quick fixes in Phase 2a do not appear here.
 
 #### Output format
 
@@ -195,7 +229,7 @@ These are defaults. Always include any section where items were actually found,
 
 ### Phase 3: Execution
 
-Parse the user's response and execute confirmed actions.
+Parse the user's response to the Phase 2b action menu and execute confirmed actions.
 
 #### Response parsing
 
@@ -246,6 +280,18 @@ After all actions are processed, present a concise report:
 
 Omit empty sections. Use the item's original ID (F1, L1, I2) so the developer can cross-reference with the inventory.
 
+### Phase 5: PR prompt
+
+After the results report, check whether the branch has commits ahead of the default branch (`git log --oneline {default_branch}..HEAD`). If there are commits — whether from the session's earlier work, quick fixes applied in Phase 2a, or both — prompt the user to create a PR:
+
+```
+Ready to create a PR? Use `/summarize-change` to generate a change summary, then `/create-pr` to open the pull request.
+```
+
+Skip this prompt if there are no commits on the branch (e.g., a research/exploration session with no code changes).
+
+This is advisory — not an action in a numbered menu. Consistent with the "never auto-execute" constraint.
+
 ## Ticket title conventions
 
 When creating tickets for deferred items, follow the conventions from the issue description: