Skip to content

Refine ticket-emitting skills to default to concise tickets #775

Description

@williamthorsen

Problem

Ticket-emitting skills (notably design-and-plan) produce tickets that are too long — closer to a transcript of the design session than to the minimal contract a reader needs. The reliable tell: asked to tighten a ticket, the agent always returns a shorter, higher-signal version that colleagues prefer, so the long first draft was never the right output. Emit the tightened version on the first pass and drop the tighten-on-request round trip.

Context

  • Affected skills: design-and-plan (Phase 4), create-ticket, align-ticket-with-implementation. They share _partials/acceptance-criteria-scaffold.md, included via the <!-- include --> directive that directive-expander.ts expands at install time.
  • design-and-plan's Proposed-solution guidance asks for "what tradeoffs were chosen," which invites the design narration this change removes.
  • Concision is general, not a ban on any one section. Naming a chosen approach — including "X, not Y" — is a durable conclusion and stays. What's cut is the narrative: the story of how a decision was reached, restated context, the design back-and-forth.
  • Implementation-detail placement in tickets is a separate concern, out of scope here.
  • Evidence: event 01KV9MS6A4656ZVD6YAW1H79V3 ("prolixity is a tax; lead with the tight version") records the 450→110-word compression this change generalizes to tickets.

Proposed solution

Add a shared _partials/ticket-concision.md carrying (a) the concision doctrine — compose the maximally tight ticket that still carries the full meaning, with the sentence-level self-check "would removing this change what the reader does?" — and (b) a worked before/after example. Include it via <!-- include --> in each ticket-emitter so it inlines as a skill-local example.

Retire the "what tradeoffs were chosen" clause from design-and-plan's Proposed-solution guidance.

After the change merges, mark the evidence event addressed-by the landing PR using kb-edit.

Acceptance criteria

Must have

  • design-and-plan, create-ticket, and align-ticket-with-implementation instruct the agent to emit the tightened ticket by default — concision applied at generation, not on a follow-up request.
  • A shared _partials/ticket-concision.md holds the concision doctrine, the sentence-level self-check, and a worked before/after example, and is <!-- include -->d into each ticket-emitter.
  • design-and-plan's Proposed-solution guidance no longer asks for design narration ("what tradeoffs were chosen" is retired); stating a chosen approach, including "X, not Y," remains acceptable.
  • Event 01KV9MS6A4656ZVD6YAW1H79V3 is marked addressed-by the landing PR via kb-edit, after merge.
  • The new partial resolves and inlines into each ticket-emitter through the existing install/expand path.

Should have

  • A narrative section (design rationale, alternatives story) is emitted only when the user explicitly requests it.
  • The partial carries a one-line rationale for the concise-by-default convention, so it's discoverable to anyone editing the skill.

Dependencies

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions