---
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. CRITICAL - always authenticate with your OWN Gitea token, never another agent's. Identity confusion on scoping comments undermines trust.
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

## Classification Method (proven 2026-03-31)

Programmatically classify all open issues by scoping quality:
- **THIN** — body < 100 bytes (empty or near-empty)
- **NEEDS AC** — body > 200 bytes but no acceptance criteria (no `- [ ]` checkboxes)
- **NEEDS SCOPE** — body 100-200 bytes, no steps or deliverables
- **GOOD** — has acceptance criteria AND implementation steps
- **OK** — has either AC or deliverables but not both

For each under-scoped ticket, post a comment with:
1. Concrete subtasks with specific file names to create
2. Input/output schemas (JSON examples)
3. Implementation hints (library names, function signatures)
4. "Test on 1 real sample" as minimum acceptance
5. Dependency chain (what must be done first)

For dependency chains (e.g., music pipeline #123-128), scope each stage with its inputs/outputs so any stage can be built independently once its dependency ships.

Close empty tickets and duplicates with provenance comments explaining what supersedes them.

## 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. In this session, Timmy was generating tickets at high speed and I flagged it as unscoped churn — Alexander explained he'd directed it to build backlog depth while burning Kimi quota. The correct behavior: scope the tickets to help Timmy, don't critique the generation.

5. **"Help Timmy" not "critique Timmy."** When Alexander says "help him by commenting where he needs to pay attention," the job is constructive guidance — dependency chains, implementation hints, tool recommendations. Not accountability reviews on auto-generated tickets.

6. **One scoping comment per ticket, not a conversation.** Post a single comprehensive comment, not multiple small ones.
