ezra-environment/protected/skills-backup/devops/gitea-scoping-audit/SKILL.md

name, description, tags, related_skills

name	description	tags	related_skills
gitea-scoping-audit	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.	gitea scoping audit acceptance-criteria backlog-grooming	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:

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.