Issue Template Guide (v2.0)¶

Last Updated: 2026-02-10 Template Version: 2.0 (Optimized for AI Implementation)

Overview¶

The little-loops issue template has been optimized to maximize value for both AI agents during implementation and human reviewers. Version 2.0 reduces cognitive overhead by removing 8 low-value sections and adding 4 high-impact sections that appear in best-practice issues.

Key Changes: - 21 sections → 17 sections (-19%) - Enhanced AI implementation guidance - Anchor-based code references (no more line number drift) - Integration Map to identify all affected files/components - High-level Implementation Steps (agents expand into detailed plans) - Consolidated redundant sections

Quick Reference¶

Common Sections (All Issue Types)¶

Section	Required	AI Usage	Purpose
Summary	✓	HIGH	One-sentence what/why
Current Behavior	✓	HIGH	What happens now
Expected Behavior	✓	HIGH	What should happen
Motivation		MEDIUM	Why this matters (NEW v2.0)
Proposed Solution		HIGH	HOW to fix with code examples
Integration Map		HIGH	All affected files/components (NEW v2.0)
Implementation Steps		HIGH	High-level outline (NEW v2.0)
Impact	✓	HIGH	Priority/Effort/Risk with justifications
Related Key Documentation		LOW	Links to docs
Labels	✓	MEDIUM	Categorization
Status	✓	HIGH	Status footer

Type-Specific Sections¶

BUG: Steps to Reproduce, Actual Behavior, Root Cause (NEW), Error Messages, Location FEAT: Use Case (renamed from User Story), Acceptance Criteria, API/Interface (NEW) ENH: Success Metrics, Scope Boundaries EPIC: Child Issues (links to BUG/FEAT/ENH children, by ID), Coordination Scope, Acceptance Criteria (across children)

Deprecated Sections (Still Supported)¶

Context, Current Pain Point, Environment, Frequency, UI/UX Details, Data/API Impact, Edge Cases, Backwards Compatibility

Note: Deprecated sections are still parsed for backward compatibility but should not be used in new issues.

Section Details¶

Summary¶

Required for all types | AI Usage: HIGH

One-sentence description combining WHAT and WHY.

Good: - BUG: "Sprint runner crashes when processing issues with merge conflicts, blocking automated workflows" - FEAT: "Add user authentication to protect admin endpoints" - ENH: "Add retry logic to sprint runner to handle transient failures"

Bad: - "Fix the bug" (no context) - "Implement user authentication using OAuth 2.0 with JWT tokens and refresh token rotation" (too detailed)

Current Behavior¶

Required for all types | AI Usage: HIGH

Describe what currently happens. Be specific and concrete.

Example (BUG):

## Current Behavior

When `ll-sprint run` encounters an issue with merge conflicts:
1. The orchestrator processes the issue
2. Merge fails with `MERGE_FAILED` status
3. Issue is marked as failed
4. Sprint continues with remaining issues
5. Failed issue is not retried

Example (FEAT):

## Current Behavior

Admin endpoints (`/admin/*`) are publicly accessible. Any user can:
- View all user data
- Modify system settings
- Delete content

Expected Behavior¶

Required for all types | AI Usage: HIGH

Describe what should happen instead.

Example (BUG):

## Expected Behavior

After initial processing completes, failed issues should be:
1. Identified from `orchestrator.queue.failed_ids`
2. Retried sequentially using existing safe processing path
3. Updated in sprint state with retry results

Motivation ⭐ NEW¶

Optional for all types | AI Usage: MEDIUM | Human Value: HIGH

Explain WHY this issue matters. Quantify impact where possible.

Good Examples:

## Motivation

Sprint reliability is currently 60%. This enhancement would:
- Increase reliability to >90% by handling transient failures
- Save ~2 hours/week in manual reprocessing
- Enable unattended overnight sprint runs

## Motivation

Public admin endpoints represent a critical security vulnerability affecting all users. Current production deployment is at risk until this is addressed.

Bad Example:

## Motivation

This would be better.

Replaces: "Current Pain Point" (ENH only) → now all issue types can express motivation

Proposed Solution¶

Optional for all types | AI Usage: HIGH | Human Value: HIGH

Suggested approach with code examples and anchor-based references.

Key Guidelines: - ✅ Use anchor-based references (function/class names) - ❌ Avoid line numbers (they drift) - ✅ Include code examples or pseudocode - ✅ Reference existing utilities to reuse - ✅ Provide 2-3 approaches if multiple options exist

Example (with anchors):

## Proposed Solution

Add retry logic in `sprint_runner.py`:

**Location**: `_cmd_sprint_run()`, after the `orchestrator.run()` block

```python
# After orchestrator completes
failed_ids = set(orchestrator.queue.failed_ids)
if failed_ids:
    for issue in wave:
        if issue.issue_id in failed_ids:
            retry_result = process_issue_inplace(issue, config, logger)

Reuse: Existing process_issue_inplace() from issue_manager.py (function anchor: def process_issue_inplace)

Alternative: Could use IssueOrchestrator retry mode, but sequential retry is simpler and reuses tested code path.

**Bad Example (line numbers)**:
```markdown
## Proposed Solution

In sprint_runner.py at line 1847, add the retry code.

❌ Line 1847 will drift as code changes

Integration Map ⭐ NEW¶

Optional for all types | AI Usage: HIGH | Human Value: HIGH

Comprehensive enumeration of all files, components, and systems affected by this change. Critical for preventing isolated changes that break other parts of the codebase.

Purpose: Answer the question "What else needs to change?" before writing code.

Structure:

## Integration Map

### Files to Modify
- `path/to/main_file.py` - Primary change location
- `path/to/related_file.py` - Related changes needed

### Dependent Files (Callers/Importers)
- `path/to/caller1.py` - Imports `function_name()`, needs update
- `path/to/caller2.py` - Calls `ClassName`, verify compatibility
- _Use `grep -r "function_name" .` to find all references_

### Similar Patterns
- `path/to/similar1.py` - Uses same pattern, update for consistency
- `path/to/similar2.py` - Similar logic, consider refactoring together
- _Search for similar code to keep codebase consistent_

### Tests
- `tests/test_main.py` - Update existing tests
- `tests/test_integration.py` - Add integration tests for callers
- _Ensure test coverage for all affected components_

### Documentation
- `docs/API.md` - Update function signature documentation
- `README.md` - Update usage examples if public API changed
- _Keep documentation in sync with code changes_

### Configuration
- `config/settings.yaml` - Update defaults/options
- `constants.py` - Update related constants
- N/A - No configuration changes needed

Quality Guidelines: - ✅ Use grep/search to find ALL callers/importers (don't guess) - ✅ Identify similar patterns for consistency - ✅ List EVERY test file that needs updates - ✅ Include docs that reference changed behavior - ✅ Note config files, even if "no change" (shows you considered it) - ✅ Use "N/A" for categories with no changes (don't leave blank or "TBD") - ❌ Don't leave as "TBD - requires investigation" in final issue

Example (BUG):

## Integration Map

### Files to Modify
- `auth/token_validator.py` - Add expiry check in `validate_token()`

### Dependent Files (Callers/Importers)
- `api/middleware/auth_middleware.py` - Handle new `TokenExpiredError`
- `api/routes/admin.py` - Catch `TokenExpiredError`
- `api/routes/user.py` - Catch `TokenExpiredError`
- `services/background_tasks.py` - Validate tokens for async jobs
- _Found via: `grep -r "validate_token" api/ services/`_

### Similar Patterns
- `auth/refresh_token_validator.py` - Has SAME bug, fix here too
- `auth/api_key_validator.py` - Different pattern, verify expiry logic
- _Pattern: `grep -r "jwt.decode" auth/` found similar validators_

### Tests
- `tests/auth/test_token_validator.py` - Add test for expired tokens
- `tests/api/test_auth_middleware.py` - Test TokenExpiredError handling
- `tests/integration/test_admin_routes.py` - Test admin rejects expired
- `tests/integration/test_user_routes.py` - Test user rejects expired

### Documentation
- `docs/API.md` - Document TokenExpiredError in auth section
- `docs/SECURITY.md` - Update security practices
- `README.md` - N/A (internal change)

### Configuration
- `config/security.yaml` - Consider adding `token_expiry_buffer_seconds`
- N/A - No constant changes needed

Example (FEAT):

## Integration Map

### Files to Modify
- `services/user_service.py` - Add `@cache_with_redis` decorator
- `utils/cache.py` - Create cache decorator (NEW FILE)

### Dependent Files (Callers/Importers)
- `api/routes/user.py` - No changes (caching transparent)
- `api/routes/admin.py` - No changes (caching transparent)
- `services/notification_service.py` - No changes
- _Found via: `grep -r "get_user_profile" .`_

### Cache Invalidation Points (CRITICAL)
- `services/user_service.py:update_user_profile()` - Invalidate cache
- `services/user_service.py:delete_user()` - Invalidate cache
- `admin/bulk_operations.py:bulk_update_users()` - Invalidate cache
- _Every write operation needs cache invalidation!_

### Similar Patterns
- `services/org_service.py` - Should add caching (same pattern)
- `services/team_service.py` - Should add caching (same pattern)
- _Opportunity: Apply pattern consistently_

### Tests
- `tests/services/test_user_service.py` - Add cache hit/miss tests
- `tests/utils/test_cache.py` - Test cache decorator (NEW)
- `tests/integration/test_cache_invalidation.py` - Critical! (NEW)

### Documentation
- `docs/ARCHITECTURE.md` - Add caching layer to architecture diagram
- `docs/CACHING.md` - Document caching strategy (NEW)
- `README.md` - Add Redis to installation instructions

### Configuration
- `config/cache.yaml` - Redis connection settings (NEW)
- `docker-compose.yml` - Add Redis service
- `.env.example` - Add REDIS_URL example

Why This Section Matters:

Common failure pattern WITHOUT Integration Map:

Fix auth.py → Deploy → Breaks API routes → Breaks background jobs →
Stale tests pass → Docs outdated → Users confused

Success pattern WITH Integration Map:

Identify all 4 callers → Fix all 4 → Update all 4 tests →
Update docs → Complete change → No breakage

Pro tip: If you find yourself saying "I'll just fix this one file", you're missing integration points. Use grep to be sure.

Implementation Steps ⭐ NEW¶

Optional for all types | AI Usage: HIGH | Human Value: MEDIUM

High-level outline that guides the implementation agent. Keep it to 3-8 major phases.

Important: This is NOT a replacement for the detailed implementation plan that /ll:manage-issue creates. Think of it as an outline the agent will expand.

Good Example (High-Level):

## Implementation Steps

1. Add retry logic after orchestrator completes
2. Identify failed issues and retry sequentially
3. Update sprint state with retry results
4. Add tests for retry behavior

Bad Example (Too Detailed):

## Implementation Steps

1. In sprint_runner.py, locate the _cmd_sprint_run() function at line 1847
2. After the orchestrator.run() call, insert a new code block
3. Call orchestrator.queue.failed_ids to get the set of failed IDs
4. Create a for loop that iterates over the wave variable
5. Inside the loop, check if issue.issue_id is in the failed_ids set
6. If true, call process_issue_inplace() with parameters: issue, config, logger
7. Capture the return value in a variable called retry_result
... (12 more steps)

❌ Too granular - this is what the agent creates during planning

Impact¶

Required for all types | AI Usage: HIGH | Human Value: HIGH

Priority, effort, and risk assessment with justifications.

New Format (v2.0):

## Impact

- **Priority**: P2 - Blocks sprint reliability; affects daily workflow
- **Effort**: Small-Medium - Reuses existing `process_issue_inplace()`, adds ~15 LOC
- **Risk**: Low - Sequential retry uses existing safe code path, no concurrency concerns
- **Breaking Change**: No

Quality Guidelines: - ✅ Justify priority: Why P0? Why P2? What's the urgency? - ✅ Justify effort: Reuses code? New patterns? Estimated LOC? - ✅ Justify risk: Breaking change? Well-tested path? Edge cases?

Bad Example:

## Impact

- **Priority**: P2
- **Effort**: Medium
- **Risk**: Low

❌ No justifications

Root Cause ⭐ NEW (BUG only)¶

Conditional for BUG | AI Usage: HIGH | Human Value: HIGH

Identify WHERE and WHY the bug occurs using anchor-based references.

Format:

## Root Cause

- **File**: `scripts/little_loops/sprint_runner.py`
- **Anchor**: `in function _cmd_sprint_run()`, after orchestrator execution
- **Cause**: Orchestrator marks issues as failed but doesn't trigger retry. The function returns after first processing pass without checking for retryable failures.

Quality Guidelines: - ✅ Use function/class anchors, not line numbers - ✅ Explain WHY the bug happens (logic error, missing check, race condition, etc.) - ✅ Reference specific code patterns or control flow

API/Interface ⭐ NEW (FEAT/ENH)¶

Conditional for FEAT/ENH | AI Usage: HIGH | Human Value: MEDIUM

Document public API contracts, interface changes, or CLI arguments.

Example (Function Signature):

## API/Interface

```python
def authenticate_user(username: str, password: str) -> AuthToken:
    """Authenticate user and return session token.

    Args:
        username: User's login name
        password: User's password (will be hashed)

    Returns:
        AuthToken with expiry and permissions

    Raises:
        AuthenticationError: If credentials are invalid
    """

Example (CLI Change):

## API/Interface

New CLI flag for `ll-sprint`:

```bash
ll-sprint run --retry-failed

Flag: --retry-failed / -r
Type: boolean (default: false)
Behavior: Retry failed issues sequentially after initial processing

Breaking Change: No (opt-in flag)

**Consolidates**: "Data/API Impact" (deprecated)

---

### Use Case (FEAT only) - Renamed from "User Story"
**Required for FEAT | AI Usage: HIGH | Human Value: HIGH**

Describe a **concrete scenario** showing who uses this and what they achieve.

**Good Example**:
```markdown
## Use Case

**Who**: DevOps engineer running overnight sprint processing

**Context**: They've configured a sprint with 50 issues and want to run it unattended overnight.

**Goal**: When transient failures occur (network timeouts, temporary merge conflicts), the sprint should automatically retry failed issues instead of requiring manual intervention the next morning.

**Outcome**: Sprint completes with 95%+ success rate, failed issues are logged for review, and engineer has actionable results in the morning.

Bad Example:

## Use Case

As a user, I want the sprint to retry failures so that I don't have to manually reprocess.

❌ Generic template, no concrete context

Quality Checks¶

All Issues¶

[ ] Impact includes justifications for priority, effort, and risk
[ ] Proposed Solution uses anchor-based references (function/class names) not line numbers
[ ] Implementation Steps (if present) are high-level outline, not detailed plan
[ ] Summary is one sentence combining WHAT and WHY

BUG-Specific¶

[ ] Steps to Reproduce has numbered concrete steps (not "do the thing")
[ ] Expected vs Actual describe different specific behaviors (not just "it should work")
[ ] Error messages include actual error text, not just "there's an error"
[ ] Root Cause identifies file + function anchor + explanation (not just "investigate")

FEAT-Specific¶

[ ] Use Case describes a concrete scenario with context, not a generic template
[ ] Acceptance Criteria are individually testable with clear pass/fail
[ ] API/Interface documents signatures/schemas if introducing public contracts
[ ] Proposed Solution includes code examples or pseudocode

ENH-Specific¶

[ ] Motivation explains WHY with quantified impact where possible
[ ] Success Metrics have numeric targets or clear before/after comparison
[ ] Scope Boundaries list specific exclusions, not just "keep it simple"
[ ] Proposed Solution references existing utilities/patterns to reuse

EPIC-Specific¶

[ ] Child Issues are enumerated (via children: frontmatter or parent: EPIC-NNN references in child issues)
[ ] Each child is itself implementable (not a placeholder)
[ ] Coordination Scope is bounded: clearly states what is and is not in scope across the children
[ ] Acceptance Criteria describe cross-child outcomes, not duplicate per-child criteria

Migration Guide¶

For New Issues¶

Use /ll:capture-issue or /ll:format-issue - they automatically use the v2.0 template.

For Existing Issues¶

Existing issues continue to work without changes. Deprecated sections are still parsed.

To upgrade an existing issue to v2.0: 1. Run /ll:format-issue <issue-file> - it will offer to add new sections 2. Manually migrate: - Add "Motivation" if you had "Current Pain Point" (ENH) - Add "Implementation Steps" if you want to guide the agent - Add "Root Cause" if you know where/why the bug occurs (BUG) - Rename "User Story" to "Use Case" and enhance with concrete scenario (FEAT) - Replace line numbers in "Proposed Solution" with function/class anchors - Add justifications to "Impact" section

Examples¶

Complete BUG Issue (v2.0)¶

# BUG: Sprint runner doesn't retry failed issues

## Summary

Sprint runner marks issues as failed but doesn't retry them, requiring manual reprocessing and reducing automation reliability.

## Current Behavior

When `ll-sprint run` encounters an issue with merge conflicts or transient errors:
1. The orchestrator processes the issue
2. Issue fails with `MERGE_FAILED` or error status
3. Issue is marked as failed in sprint state
4. Sprint continues with remaining issues
5. Failed issue is never retried

## Expected Behavior

After initial processing completes:
1. Failed issues are identified from `orchestrator.queue.failed_ids`
2. Each failed issue is retried sequentially
3. Sprint state is updated with retry results
4. Final summary shows original failures vs retry successes

## Motivation

Sprint reliability is currently 60% due to transient merge conflicts. This enhancement would:
- Increase reliability to >90% by handling transient failures
- Save ~2 hours/week in manual reprocessing
- Enable unattended overnight sprint runs

## Root Cause

- **File**: `scripts/little_loops/sprint_runner.py`
- **Anchor**: `in function _cmd_sprint_run()`, after orchestrator execution
- **Cause**: Orchestrator marks issues as failed but doesn't trigger retry. Function returns after first processing pass without checking for retryable failures.

## Proposed Solution

Add retry logic in `sprint_runner.py`:

**Location**: `_cmd_sprint_run()`, after the `orchestrator.run()` block

```python
# After orchestrator completes
failed_ids = set(orchestrator.queue.failed_ids)
if failed_ids:
    logger.info(f"Retrying {len(failed_ids)} failed issues sequentially...")
    for issue in wave:
        if issue.issue_id in failed_ids:
            retry_result = process_issue_inplace(issue, config, logger)
            # Update sprint state with retry result

Reuse: Existing process_issue_inplace() from issue_manager.py

Integration Map¶

Files to Modify¶

scripts/little_loops/sprint_runner.py - Add retry logic in _cmd_sprint_run()

Dependent Files (Callers/Importers)¶

N/A - Sprint runner is top-level command, no callers in codebase

Similar Patterns¶

scripts/little_loops/cli.py - Consider adding retry to ll-auto as well
Pattern: Sequential processing of issues appears in multiple commands

Tests¶

scripts/tests/test_sprint.py - Add test for retry behavior after failures
scripts/tests/integration/test_sprint_reliability.py - Integration test (NEW)

Documentation¶

docs/CLI-TOOLS-AUDIT.md - Update ll-sprint capabilities
README.md - Update ll-sprint feature list

Configuration¶

N/A - No configuration changes needed

Implementation Steps¶

Add retry logic after orchestrator completes
Identify failed issues and retry sequentially
Update sprint state with retry results
Add tests for retry behavior

Steps to Reproduce¶

Create a sprint with an issue that has merge conflicts
Run ll-sprint run sprint-name
Observe orchestrator fails the issue
Check sprint state - issue marked as failed, no retry

Actual Behavior¶

Issue is marked as failed, sprint continues, no retry occurs.

Impact¶

Priority: P2 - Blocks sprint reliability; affects daily workflow
Effort: Small-Medium - Reuses existing function, adds ~15 LOC
Risk: Low - Sequential retry uses existing safe code path
Breaking Change: No

Labels¶

bug, sprint, reliability

Status¶

Open | Created: 2026-02-10 | Priority: P2

### Complete FEAT Issue (v2.0)

```markdown
# FEAT: Add user authentication to admin endpoints

## Summary

Add authentication to admin endpoints to prevent unauthorized access to sensitive operations.

## Current Behavior

Admin endpoints (`/admin/*`) are publicly accessible without authentication.

## Expected Behavior

Admin endpoints require valid authentication token. Unauthorized requests return 401.

## Motivation

Public admin endpoints represent a critical security vulnerability. Current production deployment is at risk until this is addressed. Affects all users (potential data breach).

## Use Case

**Who**: System administrator managing user accounts

**Context**: Admin needs to access user management dashboard to ban a spam account. They should authenticate with their admin credentials before accessing sensitive operations.

**Goal**: Securely access admin dashboard, verify identity, perform user management tasks.

**Outcome**: Only authenticated admins can access sensitive endpoints. Audit log records who performed what action.

## Proposed Solution

Add JWT-based authentication:

1. **Auth middleware**: Create `auth_middleware.py` (see `existing_middleware.py` for pattern)
2. **Token validation**: Reuse existing `verify_jwt_token()` from `auth_utils.py`
3. **Protected routes**: Apply `@require_auth` decorator to admin endpoints

```python
from functools import wraps
from auth_utils import verify_jwt_token

def require_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization')
        if not token or not verify_jwt_token(token):
            return jsonify({'error': 'Unauthorized'}), 401
        return f(*args, **kwargs)
    return decorated

@app.route('/admin/users')
@require_auth
def admin_users():
    # existing logic

Integration Map¶

Files to Modify¶

api/middleware/auth_middleware.py - Create auth middleware (NEW FILE)
api/routes/admin.py - Apply @require_auth decorator
api/routes/users.py - Apply decorator to user management routes

Dependent Files (Callers/Importers)¶

All admin route handlers - Need to import and apply decorator
Found via: grep -r "@app.route('/admin" api/

Similar Patterns¶

api/middleware/rate_limit.py - Similar decorator pattern, reuse structure
Other protected routes - Consider applying consistent auth pattern

Tests¶

tests/api/test_auth_middleware.py - Test middleware functionality (NEW)
tests/api/test_admin_routes.py - Update to include auth token in requests
tests/api/test_users_routes.py - Update to test auth rejection
tests/integration/test_admin_security.py - End-to-end security test (NEW)

Documentation¶

docs/API.md - Document authentication requirements
docs/SECURITY.md - Add authentication section
README.md - Update setup instructions for JWT configuration

Configuration¶

config/auth.yaml - Add JWT secret and token settings (NEW)
.env.example - Add JWT_SECRET example
docker-compose.yml - No changes needed

Implementation Steps¶

Create authentication middleware
Add JWT token verification
Apply @require_auth decorator to admin routes
Add authentication tests
Update API documentation

Acceptance Criteria¶

[ ] All /admin/* endpoints require valid JWT token
[ ] Requests without token return 401 Unauthorized
[ ] Requests with invalid token return 401 Unauthorized
[ ] Requests with valid token proceed normally
[ ] Audit log records authenticated admin actions

API/Interface¶

Protected Endpoints:

GET  /admin/users     - Requires: Bearer token
POST /admin/users/:id - Requires: Bearer token + admin role
DELETE /admin/content - Requires: Bearer token + admin role

Authentication Header:

Authorization: Bearer <jwt-token>

Error Response:

{
  "error": "Unauthorized",
  "message": "Valid authentication token required"
}

Impact¶

Priority: P0 - Critical security vulnerability in production
Effort: Small - Reuses existing JWT utilities, adds decorator pattern (~50 LOC)
Risk: Medium - Changes authentication flow, requires careful testing
Breaking Change: Yes - Clients must include auth token (migration plan needed)

Labels¶

feature, security, authentication, breaking-change

Status¶

Open | Created: 2026-02-10 | Priority: P0

---

## Template Variants

### Full Template (v2.0)
Includes all non-deprecated sections. Use for important issues.

**Sections**: Summary, Current Behavior, Expected Behavior, Motivation, Proposed Solution, Implementation Steps, Impact, Related Key Documentation, Labels, Status + type-specific sections

### Minimal Template
Core sections only. Use for quick captures that will be refined later.

**Sections**: Summary, Current Behavior, Expected Behavior, Impact, Status

### Legacy Template
Backward compatible with v1.0. Includes deprecated sections.

**Use only if**: You need to maintain exact compatibility with old tooling

---

## Best Practices

### For AI Implementation
1. **Use anchors, not line numbers**: `in function foo()` not `at line 42`
2. **Show code examples**: Agents work better with concrete examples
3. **Reference existing patterns**: Point to code to reuse
4. **High-level steps**: Let the agent create the detailed plan

### For Human Reviewers
1. **Quantify impact**: "affects 100 users" not "affects users"
2. **Concrete scenarios**: Show real use cases, not templates
3. **Justify decisions**: Why P0? Why high effort?
4. **Link docs**: Help reviewers find context quickly

### For Issue Quality
1. **PASS /ll:ready-issue**: Auto-validation catches common issues
2. **Use /ll:format-issue**: Interactive Q&A improves quality
3. **Include Motivation**: Helps prioritization and buy-in
4. **Write Implementation Steps**: Guides the agent, speeds implementation

---

## FAQ

**Q: Are old issues still valid?**
A: Yes. Deprecated sections are still parsed for backward compatibility.

**Q: Should I migrate all existing issues?**
A: No. Only migrate when actively working on them. `/ll:format-issue` offers optional migration.

**Q: What happened to "User Story"?**
A: Renamed to "Use Case" to encourage concrete scenarios over generic templates.

**Q: Why remove "Context"?**
A: 0% usage by agents during implementation. Keep it in "Related Key Documentation" if needed.

**Q: Difference between "Implementation Steps" and agent's implementation plan?**
A: Implementation Steps = high-level outline (3-8 phases). Agent's plan = detailed execution (20+ steps with code). Think: outline vs full plan.

**Q: When to use "Root Cause" vs "Location"?**
A: Both! "Location" = where (file/line/code from scan). "Root Cause" = why (explanation of the bug logic).

---

## Frontmatter Fields

Issue files may include a YAML frontmatter block at the top of the file. The following fields are recognized:

| Field | Type | Default | Purpose |
|-------|------|---------|---------|
| `captured_at` | ISO 8601 UTC datetime | — | Exact timestamp when the issue was captured (set by `capture-issue`) |
| `completed_at` | ISO 8601 UTC datetime | — | Set when issue status is updated to `done` in frontmatter (by `manage-issue` skill, `ll-auto`, or `ll-parallel`) |
| `discovered_date` | ISO 8601 datetime | — | When the issue was identified |
| `discovered_by` | string | — | Tool or person that created the issue |
| `confidence_score` | int (0–100) | absent | Readiness score from `/ll:confidence-check` |
| `outcome_confidence` | int (0–100) | absent | Outcome confidence score from `/ll:confidence-check` |
| `score_complexity` | int (0–25) | absent | Outcome criterion A – Complexity, from `/ll:confidence-check` |
| `score_test_coverage` | int (0–25) | absent | Outcome criterion B – Test Coverage, from `/ll:confidence-check` |
| `score_ambiguity` | int (0–25) | absent | Outcome criterion C – Ambiguity, from `/ll:confidence-check` |
| `score_change_surface` | int (0–25) | absent | Outcome criterion D – Change Surface / Fanout Verifiability, from `/ll:confidence-check` |
| `testable` | bool | absent (= true) | Set to `false` to skip Phase 3a (Write Tests — Red) when `tdd_mode: true` |
| `size` | string | absent | Size label written by `/ll:issue-size-review`: `Small`, `Medium`, `Large`, or `Very Large` |
| `decision_needed` | bool | absent | Set to `true` by `/ll:refine-issue --auto` when 2+ implementation options are deposited into `Proposed Solution`; signals automated pipelines (`ll-auto`, `ll-parallel`) to invoke `/ll:decide-issue` before implementation; cleared to `false` by `/ll:decide-issue` after the winning option is annotated |
| `missing_artifacts` | bool | absent | Set to `true` by `/ll:confidence-check` (Phase 4.7) when Outcome Risk Factors contain signal phrases indicating absent pre-condition files or unwired components (e.g., "not yet created", "does not exist", "needs wiring"); suppressed for co-deliverable files listed in `### Files to Create`; routes autodev to `/ll:wire-issue` before attempting size-review |
| `implementation_order_risk` | bool | absent | Set to `true` by `/ll:confidence-check` (Phase 4.9) when Outcome Risk Factors contain implementation ordering advice (e.g., "co-deliverable", "implement tests first", "write tests before"); captures ordering concerns that are NOT pre-condition wiring gaps and therefore must NOT trigger the wire repair path |
| `parent` | string | absent | Bare issue ID of the parent issue that was decomposed to create this child (e.g., `ENH-179`). Written automatically by `/ll:issue-size-review` (Phase 4 and Phase 6) when generating child issues. Machine-readable; used alongside the `## Parent Issue` body section for parent→child tracing. |
| `depends_on` | list of strings | absent | Soft ordering prerequisites — preferred ordering before this issue is started, but not wave-gated (sprint proceeds without waiting). Use when sequencing is desirable but not strictly required. |
| `relates_to` | list of strings | absent | Thematically related issue IDs with no ordering constraint. Used for cross-reference and discoverability; does not affect sprint wave scheduling. |
| `duplicate_of` | string | absent | Bare issue ID of the issue this duplicates. Set when closing a duplicate; routes automated pipelines to the canonical issue instead. |
| `labels` | list of strings | absent | Cross-cutting classification labels (e.g., `fsm`, `cli`, `quick-win`). Used by `ll-issues list --label`, `ll-auto --label`, `ll-sprint --label`, and `ll-parallel --label` to scope processing to a specific component or effort tier. Synced to GitHub labels on push. |
| `milestone` | string | absent | Sprint or milestone name this issue is assigned to (e.g., `sprint-2026-q2`). Written automatically by `ll-sprint run` when the sprint starts. Used by `ll-issues list --milestone` to filter issues by sprint, and by `ll-sync` to assign issues to the corresponding GitHub milestone on push. |

### `testable: false`

When `tdd_mode: true` is enabled in `ll-config.json`, `manage-issue` normally writes failing tests (Phase 3a) before implementation. For issues where automated testing is not applicable — such as documentation-only changes, prompt-file edits, or configuration-only updates — set `testable: false` in the issue frontmatter to skip Phase 3a automatically.

**Absence means testable**: only set `testable: false` explicitly for issues that opt out of the test phase. Do not set `testable: true` — it is the default.

```yaml
---
captured_at: 2026-03-17T14:32:07Z
completed_at: 2026-03-17T15:02:41Z
discovered_date: 2026-03-17T00:00:00Z
discovered_by: capture-issue
testable: false
---

manage-issue will log "⏭ Phase 3a skipped: testable: false in issue frontmatter" and proceed directly to implementation.

CONTRIBUTING.md - Issue creation workflow
API.md - Python module reference for issue parsing
ARCHITECTURE.md - System design and issue lifecycle

Issue Template Guide (v2.0)¶

Overview¶

Quick Reference¶

Common Sections (All Issue Types)¶

Type-Specific Sections¶

Deprecated Sections (Still Supported)¶

Section Details¶

Summary¶

Current Behavior¶

Expected Behavior¶

Motivation ⭐ NEW¶

Proposed Solution¶

Integration Map ⭐ NEW¶

Implementation Steps ⭐ NEW¶

Impact¶

Root Cause ⭐ NEW (BUG only)¶

API/Interface ⭐ NEW (FEAT/ENH)¶

Quality Checks¶

All Issues¶

BUG-Specific¶

FEAT-Specific¶

ENH-Specific¶

EPIC-Specific¶

Migration Guide¶

For New Issues¶

For Existing Issues¶

Examples¶

Complete BUG Issue (v2.0)¶

Integration Map¶

Files to Modify¶

Dependent Files (Callers/Importers)¶

Similar Patterns¶

Tests¶

Documentation¶

Configuration¶

Implementation Steps¶

Steps to Reproduce¶

Actual Behavior¶

Impact¶

Labels¶

Status¶

Integration Map¶

Files to Modify¶

Dependent Files (Callers/Importers)¶

Similar Patterns¶

Tests¶

Documentation¶

Configuration¶

Implementation Steps¶

Acceptance Criteria¶

API/Interface¶

Impact¶

Labels¶

Status¶

Related Documentation¶