Ticket templates push authors toward solution specs instead of problem statements #242

New issue

Open

opened 2026-04-17 19:20:18 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-17 19:20:18 +00:00

Contributor

Type

Bug

Lineage

Standalone — surfaced 2026-04-17 during Utah Invitational payment incident. Tickets basketball-api #486 and #488 were authored with prescriptive implementation details. Lucas flagged: "that's why when writing tickets we focus on user story and context for the problem — we shouldn't be solutionizing and engineering beyond architecture designs when we write tickets."

Repo

forgejo_admin/claude-custom (pal-e-agency project)

User Story

As a ticket author, I write tickets with user story, problem context, and acceptance criteria only — so implementation details stay with the dev agent (where live-code grounding prevents drift) and reviewers validate scope instead of correcting stale line numbers.

What Broke

Current ticket templates lead authors to over-specify. Authors fill in file paths with line numbers, required constants, import patterns, code snippets — then those details drift stale between ticketing and execution, forcing the review gate to waste budget on implementation corrections instead of scope validation.

Repro Steps

Open template-issue-bug or template-issue-feature in pal-e-docs
Read the "File Targets" / "Expected Behavior" examples
Author a ticket using that scaffolding
Observe: the ticket accumulates line numbers, code snippets, required module layouts

Concrete instance: basketball-api #488 authored 2026-04-17 with "6 call sites" at specific line numbers. Review pass 1 found 8 sites total and 4 of 6 line numbers stale against current main. Reviewer spent its budget correcting implementation details instead of validating scope.

Expected Behavior

Templates and authoring SOP emphasize the three things that matter: user story, problem context, acceptance criteria. Implementation specifics are guided by architecture docs or derived by the dev agent from live code. Templates should explicitly discourage line-number precision and code snippets.

Environment

Affected notes (pal-e-docs): template-issue, template-issue-bug, template-issue-feature, template-issue-spike
Affected SOP: whichever documents ticket authoring (none explicit today — gap is part of the problem)
Evidence incidents: basketball-api #486 + #488 review cycles on 2026-04-17

Acceptance Criteria

Ticket templates foreground user story / problem context / acceptance criteria; de-emphasize prescriptive implementation sections
SOP exists (or is updated) teaching the convention with a good-example / bad-example contrast
Review-ticket skill expectations align — reviewers validate scope, not implementation detail

project-pal-e-agency
Memory: feedback_tickets_not_solution_specs.md
basketball-api #486, #488 — incident tickets that motivated this

### Type Bug ### Lineage Standalone — surfaced 2026-04-17 during Utah Invitational payment incident. Tickets basketball-api #486 and #488 were authored with prescriptive implementation details. Lucas flagged: "that's why when writing tickets we focus on user story and context for the problem — we shouldn't be solutionizing and engineering beyond architecture designs when we write tickets." ### Repo `forgejo_admin/claude-custom` (pal-e-agency project) ### User Story As a ticket author, I write tickets with user story, problem context, and acceptance criteria only — so implementation details stay with the dev agent (where live-code grounding prevents drift) and reviewers validate scope instead of correcting stale line numbers. ### What Broke Current ticket templates lead authors to over-specify. Authors fill in file paths with line numbers, required constants, import patterns, code snippets — then those details drift stale between ticketing and execution, forcing the review gate to waste budget on implementation corrections instead of scope validation. ### Repro Steps 1. Open `template-issue-bug` or `template-issue-feature` in pal-e-docs 2. Read the "File Targets" / "Expected Behavior" examples 3. Author a ticket using that scaffolding 4. Observe: the ticket accumulates line numbers, code snippets, required module layouts Concrete instance: basketball-api #488 authored 2026-04-17 with "6 call sites" at specific line numbers. Review pass 1 found 8 sites total and 4 of 6 line numbers stale against current main. Reviewer spent its budget correcting implementation details instead of validating scope. ### Expected Behavior Templates and authoring SOP emphasize the three things that matter: user story, problem context, acceptance criteria. Implementation specifics are guided by architecture docs or derived by the dev agent from live code. Templates should explicitly discourage line-number precision and code snippets. ### Environment - Affected notes (pal-e-docs): `template-issue`, `template-issue-bug`, `template-issue-feature`, `template-issue-spike` - Affected SOP: whichever documents ticket authoring (none explicit today — gap is part of the problem) - Evidence incidents: basketball-api #486 + #488 review cycles on 2026-04-17 ### Acceptance Criteria - [ ] Ticket templates foreground user story / problem context / acceptance criteria; de-emphasize prescriptive implementation sections - [ ] SOP exists (or is updated) teaching the convention with a good-example / bad-example contrast - [ ] Review-ticket skill expectations align — reviewers validate scope, not implementation detail ### Related - `project-pal-e-agency` - Memory: `feedback_tickets_not_solution_specs.md` - basketball-api #486, #488 — incident tickets that motivated this