126 lines
5.0 KiB
Markdown
126 lines
5.0 KiB
Markdown
---
|
|
name: gitea-scoping-audit
|
|
description: Audit a Gitea backlog for scoping quality — identify thin tickets, add acceptance criteria, break epics into subtasks, close duplicates, and post actionable guidance comments. Use when Alexander asks to "scope", "ground", or "break out" tickets.
|
|
tags: [gitea, scoping, audit, acceptance-criteria, backlog-grooming]
|
|
related_skills: [gitea-board-triage, gitea-project-management]
|
|
---
|
|
|
|
# Gitea Scoping Audit
|
|
|
|
## When to Use
|
|
- Alexander asks to "scope", "ground acceptance criteria", or "break out tasks"
|
|
- Backlog has thin tickets (2-3 sentence descriptions with no AC)
|
|
- Auto-generated tickets from Kimi/Gemini burn sessions need grounding
|
|
- Before sprint planning — tickets need to be executable
|
|
|
|
## The Scoping Quality Test
|
|
|
|
Read every open issue body and classify:
|
|
|
|
```python
|
|
has_ac = any(kw in body.lower() for kw in ['acceptance criteria', '- [ ]', '- [x]', 'criteria'])
|
|
has_deliverables = any(kw in body.lower() for kw in ['deliverable', 'output', 'produces'])
|
|
has_steps = any(kw in body.lower() for kw in ['step ', 'steps', '1.', '## how', '## implementation'])
|
|
body_len = len(body)
|
|
|
|
if body_len < 100:
|
|
quality = "THIN" # Almost empty, needs full rewrite
|
|
elif has_ac and has_steps:
|
|
quality = "GOOD" # Ready to execute
|
|
elif has_ac or has_deliverables:
|
|
quality = "OK" # Minimal but workable
|
|
elif body_len > 200 and not has_ac:
|
|
quality = "NEEDS AC" # Has content but no acceptance criteria
|
|
else:
|
|
quality = "NEEDS SCOPE" # Vague, needs breakdown
|
|
```
|
|
|
|
## What a Well-Scoped Ticket Looks Like
|
|
|
|
Every ticket should have:
|
|
1. **Concrete deliverables** — specific file names, not "implement a system"
|
|
2. **Input/output schema** — what goes in, what comes out (JSON examples)
|
|
3. **Acceptance criteria** — `- [ ]` checkboxes that are testable
|
|
4. **Dependencies** — "depends on #N" if sequenced
|
|
5. **Implementation guidance** — not full code, but enough that the implementer knows WHERE to start
|
|
|
|
### Template for scoping comments:
|
|
|
|
```
|
|
## Ezra Scoping Pass
|
|
|
|
### Deliverable: `scripts/specific_name.py`
|
|
**Input:** [what it takes]
|
|
**Output:** [what it produces, with example schema]
|
|
|
|
### Subtask 1: [first concrete step]
|
|
**File:** [exact path]
|
|
**What it does:** [one sentence]
|
|
|
|
### Subtask 2: [second step]
|
|
...
|
|
|
|
### Acceptance Criteria
|
|
- [ ] [Testable condition 1]
|
|
- [ ] [Testable condition 2]
|
|
- [ ] Test: [specific test to run]
|
|
```
|
|
|
|
## Common Scoping Patterns
|
|
|
|
### Pattern 1: Pipeline Decomposition
|
|
When a ticket describes a multi-stage pipeline (e.g., "build video analysis"):
|
|
- Create one ticket per stage with explicit input → output
|
|
- Add dependency chain: #123 → #124 → #125
|
|
- Final ticket is the orchestrator that calls all stages
|
|
- Each stage is independently testable
|
|
|
|
### Pattern 2: Research → Decision → Implementation
|
|
When a ticket mixes research with building:
|
|
- Split into: research spike (produces a finding document) + implementation ticket (references the finding)
|
|
- Research ticket closes with a recommendation, not code
|
|
- Implementation ticket opens only if research recommends proceeding
|
|
|
|
### Pattern 3: Epic → Sprint Tickets
|
|
When a ticket is really an epic (too big for one PR):
|
|
- Post a breakdown comment listing subtasks
|
|
- Each subtask should be ≤500 lines of code change
|
|
- First subtask should be "scaffold + tests" that subsequent subtasks fill in
|
|
|
|
### Pattern 4: Duplicate Consolidation
|
|
When multiple tickets cover the same ground:
|
|
- Close the thinner one with "Duplicate of #N"
|
|
- Add the unique content from the closed ticket as a comment on the surviving ticket
|
|
|
|
## Steps
|
|
|
|
1. **Fetch all open issues** via execute_code + urllib (same as gitea-board-triage)
|
|
|
|
2. **Classify each** by scoping quality using the test above
|
|
|
|
3. **For THIN tickets**: Either close (if truly empty) or rewrite with full scope
|
|
|
|
4. **For NEEDS AC tickets**: Post a scoping comment adding:
|
|
- Concrete deliverable file names
|
|
- Input/output examples with JSON schemas
|
|
- `- [ ]` acceptance criteria
|
|
- Implementation hints
|
|
|
|
5. **For NEEDS SCOPE tickets**: Break into subtasks if too big, or add the missing structure
|
|
|
|
6. **Assign all** — no unassigned tickets after a scoping pass
|
|
|
|
7. **Identify dependency chains** and note them in comments
|
|
|
|
## Pitfalls
|
|
|
|
1. **Don't over-scope creative/research tickets.** A research spike is "done" when it produces a finding, not when it ships code. Acceptance criteria for research: "Document exists at path X with sections Y and Z."
|
|
|
|
2. **Don't scope on behalf of Alexander's judgment calls.** Tickets like "soul rewrite" or "dissolution" need Alexander's input, not Ezra's AC.
|
|
|
|
3. **Auto-generated tickets often need the MOST scoping.** Kimi/Gemini produce volume with thin descriptions. Every auto-generated ticket needs: specific files, test commands, and "done looks like X."
|
|
|
|
4. **Retract when wrong.** If you misread context (e.g., flagging deliberate backlog generation as undirected churn), update your comment immediately.
|
|
|
|
5. **One scoping comment per ticket, not a conversation.** Post a single comprehensive comment, not multiple small ones.
|