ringpre-dev-task-breakdown

name: "ring:pre-dev-task-breakdown" description: | Gate 7: Implementation tasks - value-driven decomposition into working increments that deliver measurable user value. license: MIT compatibility: opencode metadata: trigger: | - PRD passed Gate 1 (required) - TRD passed Gate 3 (required) - All Large Track gates passed (if applicable) - Ready to create sprint/iteration tasks skip_when: | - PRD or TRD not validated → complete earlier gates - Tasks already exist → proceed to Subtask Creation - Trivial change → direct implementation

sequence: after: [ring:pre-dev-trd-creation, ring:pre-dev-dependency-map] before: [ring:pre-dev-subtask-creation, ring:executing-plans]

Task Breakdown - Value-Driven Decomposition

Foundational Principle

Every task must deliver working software that provides measurable user value.

Creating technical-only or oversized tasks creates:

• Work that doesn't ship until "everything is done"
• Teams working on pieces that don't integrate
• No early validation of value or technical approach
• Waterfall development disguised as iterative process

Tasks answer: What working increment will be delivered? Tasks never answer: How to implement that increment (that's Subtasks).

Mandatory Workflow

Explicit Rules

✅ DO Include in Tasks

Task ID, title, type (Foundation/Feature/Integration/Polish), deliverable (what ships), user value (what users can do), technical value (what it enables), success criteria (testable/measurable), dependencies (blocks/requires/optional), effort estimate (AI-agent-hours with confidence), testing strategy, risk identification with mitigations, Definition of Done checklist

❌ NEVER Include in Tasks

Implementation details (file paths, code examples), step-by-step instructions (those go in subtasks), technical-only tasks with no user value, tasks exceeding 2 weeks (break them down), vague success criteria ("improve performance"), missing dependency information, undefined testing approach

Task Sizing Rules

*Calendar duration assumes 1.5x multiplier (standard validation), 90% capacity, and 1 developer

Value Delivery Rules

• Foundation: Enables other work (database setup, core services)
• Feature: Delivers user-facing capabilities
• Integration: Connects to external systems
• Polish: Optimizes or enhances (nice-to-have)

AI-Assisted Time Estimation

See shared-patterns/ai-agent-baseline.md for baseline definition.

After defining task scope and success criteria, the system automatically estimates implementation time.

Estimation Process

1. Tech Stack Detection: Identify project type from TRD

   • Go project → dispatch ring:backend-engineer-golang
   • TypeScript Backend → dispatch ring:backend-engineer-typescript
   • React/Next.js → dispatch ring:frontend-engineer
   • Mixed/Unknown → dispatch ring:codebase-explorer

2. Scope Analysis: Specialized agent analyzes:

   • Technical components (endpoints, schemas, services)
   • Complexity level (CRUD vs custom algorithms)
   • Available libraries (lib-commons, frameworks)
   • Test requirements (coverage %, test types)
   • Documentation requirements

3. Time Calculation: Agent estimates per scope item

   • Database schema + migrations
   • Repository/data layer
   • Business logic layer
   • API handlers/controllers
   • Validation logic
   • Error handling
   • Unit tests (TDD)
   • Integration tests
   • Documentation

4. Output: Total in AI-agent-hours

For detailed baseline definition and capacity explanation, see shared-patterns/ai-agent-baseline.md.

Confidence Levels

Example Output

**Effort Estimate:**
- **Baseline:** AI Agent via ring:dev-cycle
- **AI Estimate:** 4.5 AI-agent-hours
- **Estimation Method:** ring:backend-engineer-golang analysis
- **Confidence:** High (standard CRUD, lib-commons available)

**Breakdown:**
- Database schema + migrations: 0.5h
- Repository layer (CRUD): 0.5h
- Service layer (business logic): 0.5h
- HTTP handlers (4 endpoints): 1.0h
- Input validation: 0.3h
- Error handling: 0.2h
- Unit tests (TDD, 85% coverage): 0.8h
- Integration tests: 0.5h
- OpenAPI documentation: 0.2h
**Total: 4.5 AI-agent-hours**

**Assumptions:**
- lib-commons/http, lib-commons/postgres, lib-commons/validator available
- Standard CRUD patterns (no complex algorithms)
- PostgreSQL database configured
- ring:dev-cycle will execute implementation

**Team Type:** Backend Engineer (Go)

Rationalization Table

Red Flags - STOP

If you catch yourself writing any of these in a task, STOP:

• Task estimates over 2 weeks
• Tasks named "Setup X" without defining what X enables
• Success criteria like "works" or "complete" (not measurable)
• No dependencies listed (every task depends on something)
• No testing strategy (how will you verify?)
• "Technical debt" as a task type (debt reduction must deliver value)
• Vague deliverables ("improve", "optimize", "refactor")
• Missing Definition of Done

When you catch yourself: Refine the task until it's concrete, valuable, and testable.

Gate 7 Validation Checklist

Gate Result: ✅ PASS → Subtasks | ⚠️ CONDITIONAL (refine oversized/vague) | ❌ FAIL (re-decompose)

Multi-Module Task Tagging

If TopologyConfig exists in research.md frontmatter (from Gate 0):

Read Topology Configuration

# From research.md frontmatter
topology:
  scope: fullstack
  structure: monorepo | multi-repo
  modules:
    backend:
      path: packages/api
      language: golang
    frontend:
      path: packages/web
      framework: nextjs
  doc_organization: unified | per-module

Task Target Assignment

Each task MUST have target: and working_directory: fields when topology is multi-module.

Agent assignment depends on both target and api_pattern:

How to Determine Agent for Frontend Tasks

Read api_pattern from research.md frontmatter:

# From research.md
topology:
  scope: fullstack
  api_pattern: direct | bff | other

Decision Flow:

Is task target: frontend?
├─ NO → Use backend-engineer-* based on language
└─ YES → Check api_pattern
    ├─ direct → ALL frontend tasks use frontend-engineer
    └─ bff → Split tasks:
        ├─ API routes, aggregation, transformation → frontend-bff-engineer-typescript
        └─ UI components, pages, forms → frontend-engineer

Task Format with Agent Assignment

## T-003: User Login API Endpoint

**Target:** backend
**Working Directory:** packages/api
**Agent:** ring:backend-engineer-golang

**Deliverable:** Working login API that validates credentials and returns JWT token.

...rest of task...

## T-004: User Dashboard Data Aggregation

**Target:** frontend
**Working Directory:** packages/web
**Agent:** ring:frontend-bff-engineer-typescript  # Because api_pattern: bff

**Deliverable:** BFF endpoint that aggregates user profile, recent activity, and notifications.

...rest of task...

## T-005: User Dashboard UI

**Target:** frontend
**Working Directory:** packages/web
**Agent:** ring:frontend-engineer  # UI task, even with BFF pattern

**Deliverable:** Dashboard page component consuming aggregated data from BFF.

...rest of task...

Validation for Agent Assignment

Per-Module Output

Document placement depends on topology.structure:

Single-Repo

All tasks in one file:

docs/pre-dev/{feature}/
└── tasks.md           # All tasks with target tags

Monorepo (per-module placement)

Index at root, filtered tasks in module directories:

docs/pre-dev/{feature}/
└── tasks.md           # Index with ALL tasks (target tags included)

{backend.path}/docs/pre-dev/{feature}/
└── tasks.md           # Backend tasks only (target: backend)

{frontend.path}/docs/pre-dev/{feature}/
└── tasks.md           # Frontend tasks only (target: frontend)

Multi-Repo (distributed placement)

Tasks distributed to respective repositories:

{backend.path}/docs/pre-dev/{feature}/
└── tasks.md           # Backend tasks only

{frontend.path}/docs/pre-dev/{feature}/
└── tasks.md           # Frontend tasks only

Note: For multi-repo, there is no central index. Each repo contains only its relevant tasks.

Task Splitting Logic

def split_tasks_by_module(all_tasks: list, topology: dict) -> dict:
    """
    Split tasks into module-specific files.

    Returns dict with keys: 'index', 'backend', 'frontend'
    """
    structure = topology.get('structure', 'single-repo')
    modules = topology.get('modules', {})
    backend_path = modules.get('backend', {}).get('path', '.')
    frontend_path = modules.get('frontend', {}).get('path', '.')

    backend_tasks = [t for t in all_tasks if t.get('target') == 'backend']
    frontend_tasks = [t for t in all_tasks if t.get('target') == 'frontend']
    shared_tasks = [t for t in all_tasks if t.get('target') == 'shared']

    if structure == 'single-repo':
        return {
            'index': {
                'path': f"docs/pre-dev/{feature}/tasks.md",
                'tasks': all_tasks
            }
        }

    if structure == 'monorepo':
        return {
            'index': {
                'path': f"docs/pre-dev/{feature}/tasks.md",
                'tasks': all_tasks
            },
            'backend': {
                'path': f"{backend_path}/docs/pre-dev/{feature}/tasks.md",
                'tasks': backend_tasks + shared_tasks
            },
            'frontend': {
                'path': f"{frontend_path}/docs/pre-dev/{feature}/tasks.md",
                'tasks': frontend_tasks + shared_tasks
            }
        }

    if structure == 'multi-repo':
        return {
            'backend': {
                'path': f"{backend_path}/docs/pre-dev/{feature}/tasks.md",
                'tasks': backend_tasks + shared_tasks
            },
            'frontend': {
                'path': f"{frontend_path}/docs/pre-dev/{feature}/tasks.md",
                'tasks': frontend_tasks + shared_tasks
            }
        }

Module-Specific Task File Header

Each module-specific tasks.md should include:

---
feature: {feature-name}
module: backend | frontend
filtered_from: docs/pre-dev/{feature}/tasks.md  # (monorepo only)
total_tasks: N
---

# {Feature Name} - {Module} Tasks

This file contains tasks filtered for the **{module}** module.

**Full task list:** {link to index if monorepo, or note "distributed" if multi-repo}

---

Validation for Multi-Module

Task Template Structure

Output to docs/pre-dev/{feature-name}/tasks.md. Each task includes:

AI Estimation Fallback Procedure

When AI estimation fails or is unavailable:

Failure Conditions

AI estimation is considered failed when:

• ❌ Agent unreachable (API timeout >30s)
• ❌ API errors (rate limit exceeded, 500 errors)
• ❌ Service outage (Claude API down)
• ❌ Invalid response (no estimate returned)
• ❌ Scope too ambiguous (agent returns Low confidence with no estimate)

Escalation Path

1. Immediate (0-5 min): Retry once with exponential backoff
2. Short-term (5-15 min): Switch to backup agent if available
3. Medium-term (15-30 min): Notify PM team lead via Slack
4. Long-term (30+ min): Use manual estimation override (see below)

Manual Estimation Override

Who can approve: PM Team Lead or designated backup

Required evidence for override:

• Similar historical task with actual time data
• Expert estimation from technical lead (with rationale)
• Decomposed scope with per-component estimates
• Documentation of estimation method used

How to record:

**Effort Estimate:**
- AI Estimate: [FAILED - API unavailable]
- Manual Override: X hours (approved by: [Name], date: YYYY-MM-DD)
- Estimation Method: Historical comparison with Task T-XXX
- Confidence: Medium (manual estimation, subject to higher variance)
- Evidence: [Link to similar task or rationale document]

Temporary Capacity Adjustments

When manual estimation is used:

• Apply 1.3x multiplier to manual estimates (30% buffer for estimation uncertainty)
• Mark task with "Estimation Pending" flag in roadmap
• Schedule re-estimation when AI service restored
• Track variance post-completion to calibrate manual estimates

Example:

Manual estimate: 6 hours
Adjusted estimate: 6h × 1.3 = 7.8 hours
Confidence: Medium → Low (due to estimation method)
Re-estimation scheduled: [Date when AI available]

Confidence Flag Requirements

Align with rationalization table:

• ✅ Manual estimates MUST be marked with confidence level
• ✅ Include rationale for estimation method
• ✅ Link to historical data or expert judgment
• ✅ Document who approved and when
• ❌ NEVER mark manual estimates as "High" confidence
• ❌ NEVER skip variance tracking for manual estimates

Common Violations

Delivery Sequencing

Optimize task order by sprint/phase with goals, critical path identification, and parallel work opportunities.

Confidence Scoring

Action: 80+ autonomous | 50-79 present options | <50 ask about velocity

Output & After Approval

Output to (depends on topology.structure):

1. ✅ Tasks become sprint backlog
2. 🎯 Use as input for subtasks (ring:pre-dev-subtask-creation)
3. 📊 Track progress per task (not per subtask)
4. 🚫 No implementation yet - that's in subtasks

The Bottom Line

If you created tasks that don't deliver working software, rewrite them.

Tasks are not technical activities. Tasks are working increments.

"Setup database" is not a task. "User data persists correctly" is a task. "Implement OAuth" is not a task. "Users can log in with Google" is a task. "Write tests" is not a task. Tests are part of Definition of Done for other tasks.

Every task must answer: "What working software can I demo to users?"

If you can't demo it, it's not a task. It's subtask implementation detail.

Deliver value. Ship working software. Make tasks demoable.