Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/agents/content/guidance/shared/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code
## Workflow

- Questions are not instructions. When the user asks "Did you do X?", answer the question. Do not treat it as a request to do X.
- Prefer ticket-driven development. When follow-up work, new features, or deferred items are identified, ask the user whether to create a GitHub issue rather than implementing ad hoc or silently deferring.
- A ticket is a signal, not a boundary. When work surfaces that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than parking it in the conversation. Surface and recommend the scope call; the user owns the decision. Full doctrine: `_data/scope-and-deferral.md` in the agents skills tree.
- Changes should flow through the repository via branches and pull requests, not direct edits to the default branch.
- When feedback should change how the agent behaves and generalizes beyond the current task, capture it via the `capture-feedback` skill, which routes it to guidance refinement that propagates to every project and machine. Do not record generalizable guidance as a per-project memory.
- Memories are scoped to a single project on a single machine, so using them for generalizable guidance fragments behavior across contexts. Reserve them for genuinely local, non-propagating facts (a project-specific deadline or quirk).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,4 +54,4 @@ When characteristics span two levels, prefer the higher level. This is consisten

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).
The complexity rubric and the [scope-and-deferral](scope-and-deferral.md) model compose: Complexity drives orchestration-routing decisions (which skill picks the work up next), while scope-and-deferral drives the fold-in-vs-spin-off decision (whether the work needs its own ticket at all).
Original file line number Diff line number Diff line change
Expand Up @@ -72,4 +72,4 @@ The selected option carries the ■■□ marker in the rendered output. The oth

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.

See [`ticket-creation-cost.md`](ticket-creation-cost.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) composes with the recommendation rules above: The rules here pick the next-step _skill_; the cost reference governs whether work that surfaces alongside the current plan should spawn a new ticket or ship adjacent.
See [`scope-and-deferral.md`](scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) composes with the recommendation rules above: The rules here pick the next-step _skill_; that reference governs whether work that surfaces alongside the current plan should spawn a new ticket or ship adjacent.
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Complexity levels classify individual findings, but the recommendation applies t

Each skill supplies its own recommendation context (e.g., finding counts and categories, severity of deviations). Apply these rules using that context.

See [`ticket-creation-cost.md`](ticket-creation-cost.md) for the cost-aware disposition that governs whether a deferred finding becomes a separate ticket, joins a batch, or ships as a drive-by. The recommendation rules above pick the _implementation skill_; the cost reference applies to any finding that the user defers rather than addressing immediately.
See [`scope-and-deferral.md`](scope-and-deferral.md) for the cost-aware disposition that governs whether a deferred finding becomes a separate ticket, joins a batch, or ships as a drive-by. The recommendation rules above pick the _implementation skill_; that reference applies to any finding that the user defers rather than addressing immediately.

## Combined output format

Expand Down
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
# Ticket creation cost
# Scope and deferral decisions

Source of truth for cost-aware disposition of findings and follow-up items. Skills that propose ticket creation reference this document to avoid over-ticketing trivial work.
Governs one decision: when work surfaces that the ticket didn't name (a discovered defect, an adjacent cleanup, a companion change), does it fold into the current change, or spin off into a separate ticket?

The principle: Every ticket carries fixed overhead beyond the work itself. The agent must weigh that overhead before recommending a separate ticket, and route findings into the lane that best matches their weight.
## The default: fold in

## Per-ticket overhead
Work the problem requires, or that is cheap and serves the ticket's goal, folds into the current change by default. A ticket is a signal of intent, not a boundary; it belongs to us and can be refined. Spinning off a separate ticket needs an affirmative, stated reason:

A new ticket is not free. Even before any code is written, each ticket incurs:
- a genuinely separable concern,
- a materially different risk surface,
- size that would swamp the current change, or
- independent prioritization (the work can wait and competes with other backlog priorities on its own merits).

- **Backlog maintenance** — the ticket must be triaged, labeled, prioritized, and kept current alongside everything else in the backlog.
- **Familiarization** — whoever picks the ticket up later (often after context has drained) must rebuild the mental model of what was deferred and why.
- **Design and planning** — even small tickets get a plan, a branch, and an approach.
- **Implementation** — the actual code change.
- **Review** — review cycles run regardless of change size; small changes still consume reviewer attention.
- **PR creation, approval, and merge** — every change goes through the same PR-and-merge protocol.
"The ticket didn't mention it" is never such a reason, and must not be offered as one. When the discovered work addresses the same underlying problem, closing only the ticket-named part leaves the problem partially solved, so that work is required, not optional.

For a one-line vocabulary fix or a two-line cleanup, the overhead can dwarf the underlying work by an order of magnitude. Routing such items into a separate ticket is not free risk-management — it is unnecessary cost.
**Authority.** Scope is the user's decision, not the agent's. Surface discovered work, recommend a disposition with its tradeoffs, and let the user choose; never declare work "out of scope" as settled fact.

**Feature responsibility.** When the current change introduces a feature, an avoidable user-visible defect that feature causes is in-scope-by-default, a likely bug to fix here, not an automatic follow-up. Meeting the ticket's written acceptance criteria does not license shipping a defect the change itself introduced.

## Why a separate ticket is expensive

A new ticket is not free. Beyond the work itself, it commits the whole pipeline (creation, reading, evaluation, design, planning, implementation, review, checks, push, PR, approval, merge, and cleanup) and carries an opportunity cost against everything else in the backlog. Small, clean tickets yield small, clean PRs that are easy to approve; that value is real, but it must clear the pipeline-and-opportunity bar, weighed against the whole flow rather than any single step. For a one-line vocabulary fix or a two-line cleanup, the overhead can dwarf the underlying work by an order of magnitude; routing it into a separate ticket is not risk-management but unnecessary cost.

Once work is judged genuinely separable, ticket it immediately rather than parking it in the conversation; a tracker moves that state out of the user's head. That governs _how_ to defer; the fold-in default governs _whether_. The two compose: decide the disposition here, and execute create-immediately when the disposition is "separate ticket."

## Three-lane disposition model

Expand Down
2 changes: 1 addition & 1 deletion packages/agents/content/skills/_data/ticket-evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ A ticket — regardless of who created it — is a request, report, or suggestio
The author may have framed it poorly, missed the actual problem, scoped it too narrowly, proposed an unsound fix, or filed work that turns out to be inadvisable. Before designing to a ticket, evaluate it on its merits:

- **Is the problem real?** Reproduce or verify the underlying observation, not just the framing.
- **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame.
- **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame. Scope can grow, not only shrink: work the problem requires folds into the current change by default rather than deferring; see [scope-and-deferral](./scope-and-deferral.md).
- **Is the proposed solution sound?** A ticket may include a recommended fix that solves the symptom but not the cause, or that fixes the cause less well than an alternative. Apply the [design priorities](./design-priorities.md) lens — a convenient-but-wrong fix is unsound, even if it matches surrounding code.
- **Is the title accurate?** "Flaky test in X" may be a hygiene anti-pattern that exists in three places. Reframe titles when the underlying truth is broader or different.
- **Is the change worth making?** Synthesize the above: Doing nothing, or doing something narrower, may be the right call. Don't treat acceptance as the default.
Expand Down
2 changes: 1 addition & 1 deletion packages/agents/content/skills/collaborate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ This — a numbered gradient list in the message body:

When you deem appropriate, proactively dispatch subagents to perform tasks. Good examples:

- A substantive out-of-scope issue has arisen, and a separate ticket is the right disposition under the three-lane model in [`_data/ticket-creation-cost.md`](../_data/ticket-creation-cost.md) (the trivial **do now** and **batch later** lanes have already been ruled out, and the ticket content is already known). Dispatch a subagent to create the ticket while you and the developer move on.
- A substantive out-of-scope issue has arisen, and a separate ticket is the right disposition under the three-lane model in [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md) (the trivial **do now** and **batch later** lanes have already been ruled out, and the ticket content is already known). Dispatch a subagent to create the ticket while you and the developer move on.
- You are discussing multiple issues with the developer, and some of them would benefit from research. Dispatch subagents for the research while you and the developer continue to discuss the other issues.

## Skill improvement
Expand Down
2 changes: 1 addition & 1 deletion packages/agents/content/skills/design-and-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod

1. **Explore project context:** check relevant files, docs, recent commits to understand the affected area of the codebase.

2. **Evaluate the ticket on its merits** — apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation surfaces a divergence from the ticket as written, raise it to the user before forming questions or designing.
2. **Evaluate the ticket on its merits** — apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation surfaces a divergence from the ticket as written, raise it to the user before forming questions or designing. Divergence includes scope that should grow: work the problem requires folds into this change by default rather than a follow-up (see [scope-and-deferral](../_data/scope-and-deferral.md)).

3. **Ask clarifying questions** — one at a time:
- Purpose and motivation
Expand Down
8 changes: 4 additions & 4 deletions packages/agents/content/skills/wrap-up/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ Items at levels 1–2 (trivial or mechanical) are **drive-by candidates** — si

Items at levels 3–4 remain in the standard findings pool for the housekeeping menu in Phase 2b.

The complexity assessment feeds into the cost-aware disposition flow described in [`_data/ticket-creation-cost.md`](../_data/ticket-creation-cost.md): Trivial items prefer **do now** (Phase 2a drive-bys); items that can't ship as drive-bys but share scope or source prefer **batch later** (Phase 2b batch action); substantive items get a **separate ticket** (Phase 2b per-item ticketing).
The complexity assessment feeds into the cost-aware disposition flow described in [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md): Trivial items prefer **do now** (Phase 2a drive-bys); items that can't ship as drive-bys but share scope or source prefer **batch later** (Phase 2b batch action); substantive items get a **separate ticket** (Phase 2b per-item ticketing).

#### 1c. Scan for insights

Expand Down Expand Up @@ -130,7 +130,7 @@ Run `git status` and `git log --oneline {default_branch}..HEAD` to understand:

### Phase 2a: Drive-by fixes

If any findings were tagged as drive-by candidates (complexity levels 1–2) in step 1b-iii, present them for immediate action before the housekeeping menu. This is the **do now** lane from the cost-aware disposition model — see [`_data/ticket-creation-cost.md`](../_data/ticket-creation-cost.md) for the principle. Skip this phase entirely if no items qualify — do not show an empty section.
If any findings were tagged as drive-by candidates (complexity levels 1–2) in step 1b-iii, present them for immediate action before the housekeeping menu. This is the **do now** lane from the cost-aware disposition model — see [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md) for the principle. Skip this phase entirely if no items qualify — do not show an empty section.

#### Suitability check

Expand Down Expand Up @@ -171,7 +171,7 @@ Apply drive-by fixes? Reply "all", numbers, or "skip"

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 drive-by fixes in Phase 2a do not appear here.

The action menu offers two distinct ticket-creation actions ("Batch tickets for findings" and "Create tickets for findings"); their conditions and recommendation rules — drawn from the cost-aware disposition model in [`_data/ticket-creation-cost.md`](../_data/ticket-creation-cost.md) — are documented under [standard actions](#standard-actions) below.
The action menu offers two distinct ticket-creation actions ("Batch tickets for findings" and "Create tickets for findings"); their conditions and recommendation rules — drawn from the cost-aware disposition model in [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md) — are documented under [standard actions](#standard-actions) below.

#### Output format

Expand Down Expand Up @@ -230,7 +230,7 @@ The actions menu is built dynamically based on which sections are populated:
| Post insights to ticket #{n} | Insights with `ticket comment` destination | `gh issue comment` |
| Save session devlog | Always (unless trivial) | `{skill:create-devlog}` |

**Batching versus per-item ticketing.** The "Batch tickets for findings" action creates a single ticket whose body is a checklist with one entry per finding (description plus source attribution); per-item complexity levels are not repeated since they were already used to reach this phase. The "Create tickets for findings" action creates one ticket per item. These are alternatives — only one is executed for the findings pool, based on the user's selection. Recommend the batch action by default when ≥2 trivial items remain or when items share a `scope:` label or source artifact; recommend per-item ticketing when items are thematically unrelated. The "Batch tickets for findings" action implements the **batch later** lane; "Create tickets for findings" implements the **separate ticket** lane from [`_data/ticket-creation-cost.md`](../_data/ticket-creation-cost.md).
**Batching versus per-item ticketing.** The "Batch tickets for findings" action creates a single ticket whose body is a checklist with one entry per finding (description plus source attribution); per-item complexity levels are not repeated since they were already used to reach this phase. The "Create tickets for findings" action creates one ticket per item. These are alternatives — only one is executed for the findings pool, based on the user's selection. Recommend the batch action by default when ≥2 trivial items remain or when items share a `scope:` label or source artifact; recommend per-item ticketing when items are thematically unrelated. The "Batch tickets for findings" action implements the **batch later** lane; "Create tickets for findings" implements the **separate ticket** lane from [`_data/scope-and-deferral.md`](../_data/scope-and-deferral.md).

**Dropping findings.** Findings the user does not select for a ticket-creation action are implicitly dropped — menu omission is the close-without-tracking signal. The agent does not prompt to confirm; the user's selection is taken at face value. Dropped findings are still recorded in the report's `### Dropped` section and the deferred-findings artifact's `## Dropped` section so they remain discoverable.

Expand Down
Loading