Issue Templates and Smart Field Population¶

This document describes the structured issue format and intelligent field population system.

Template Enforcement¶

The .beads/templates.yaml structure is enforced when creating or updating issues:

bd_create (MCP and sync engine): Descriptions are always merged into the project template. Unstructured text becomes the Objective; partial structure gets missing sections filled from template defaults.
bd_update (MCP): When updating a description, it is merged into the template structure.
Import from ClickUp: ClickUp task descriptions are wrapped/merged into the beads template when importing.

This ensures all issues conform to the sections defined in .beads/templates.yaml.

Issue Description Structure¶

All issues should follow this structured format:

**Objective:**
Clear, concise statement of what needs to be done

**Plan:**
Step-by-step breakdown:
1. First step
2. Second step
3. Third step

**Definition of Done:**
- [ ] Acceptance criterion 1
- [ ] Acceptance criterion 2
- [ ] Acceptance criterion 3

**Testing/Evaluation Plan:**
How to verify the work is complete and correct

**Results:**
TBD (filled in after completion)

Required Sections¶

Objective: Always required - the "what" and "why"

Recommended Sections¶

Plan: Step-by-step approach (highly recommended)
Definition of Done: Checkboxes for acceptance criteria (highly recommended)
Testing/Evaluation Plan: Verification approach

Optional Sections¶

Results: Outcomes after completion
Notes: Additional context
Dependencies: Other issues this depends on
Background: Context or research

Templates by Issue Type¶

Bug Template¶

**Objective:**
Fix [describe the bug]

**Plan:**
1. Reproduce the issue
2. Identify root cause
3. Implement fix
4. Add regression test

**Definition of Done:**
- [ ] Bug no longer reproduces
- [ ] Regression test added
- [ ] No new bugs introduced

**Testing/Evaluation Plan:**
Run regression test suite and manual verification

**Results:**
TBD

Feature Template¶

**Objective:**
Implement [feature name] to [achieve goal]

**Plan:**
1. Design API/interface
2. Implement core functionality
3. Add tests
4. Update documentation

**Definition of Done:**
- [ ] Feature working as specified
- [ ] Tests passing
- [ ] Documentation updated

**Testing/Evaluation Plan:**
Unit tests, integration tests, and manual testing

**Results:**
TBD

Task Template¶

**Objective:**
Complete [task description]

**Definition of Done:**
- [ ] Task completed successfully

**Testing/Evaluation Plan:**
Manual verification

**Results:**
TBD

Epic Template¶

**Objective:**
[High-level goal or initiative]

**Plan:**
1. Break down into subtasks
2. Assign ownership
3. Track progress
4. Integrate components

**Definition of Done:**
- [ ] All subtasks completed
- [ ] Integration verified
- [ ] Stakeholders signed off

**Testing/Evaluation Plan:**
End-to-end testing and stakeholder review

**Results:**
TBD

Using Templates in Code¶

Python API¶

from beads_clickup.issue_template import IssueDescriptionValidator, get_template

# Get a template for a specific type
description = get_template("bug")

# Or format custom description
from beads_clickup.issue_template import IssueDescriptionValidator

description = IssueDescriptionValidator.format_description(
    objective="Fix authentication bug",
    plan="1. Reproduce\n2. Fix\n3. Test",
    definition_of_done="- [ ] Bug fixed\n- [ ] Tests passing"
)

# Validate existing description
is_valid, issues = IssueDescriptionValidator.validate_description(description)
if not is_valid:
    print("Issues found:", issues)

# Parse structured description
sections = IssueDescriptionValidator.parse_description(description)
print(f"Objective: {sections['Objective']}")

# Calculate completion percentage
completion = IssueDescriptionValidator.get_completion_percentage(description)
print(f"Completion: {completion}%")

Intelligent Field Population¶

The system automatically infers custom field values from issue content:

Lifecycle Stage Inference¶

Based on issue status: - completed or closed → "Delivery" - in_progress → "Implementation"

Based on issue type: - bug → "Testing & QA" - feature or epic → "High-Level Design & Architecture" - task → "Implementation"

Based on keywords in title/description: - "design", "architecture", "plan" → "High-Level Design & Architecture" - "implement", "code", "develop", "build" → "Implementation" - "test", "qa", "fix" → "Testing & QA" - "review" → "Internal Review" - "deploy", "release" → "Delivery"

Category Inference¶

Based on labels: If issue has labels like "backend", "frontend", "design", etc., those map directly to categories.

Based on issue type: - bug, feature, task → "Engineering" - epic → "Product"

Based on keywords: - "backend", "frontend", "api", "database" → "Engineering" - "design", "ui", "ux" → "Design" - "docs", "documentation" → "Documentation" - "marketing" → "Marketing" - "product" → "Product"

Effort Inference¶

Based on complexity indicators: - Count checklist items and bullet points in description - 0 items → "S" (Small) - 1-3 items → "S" - 4-6 items → "M" (Medium) - 7-10 items → "L" (Large) - 11+ items → "XL" (Extra Large)

Value Inference¶

Based on priority: - P0 → "Critical" - P1 → "High" - P2 → "Medium" - P3, P4 → "Low"

Based on keywords: - "critical", "urgent", "blocker" → "Critical" - "important", "high priority" → "High"

Found By Inference (for bugs)¶

Based on keywords: - "production", "customer", "user" → "Production" - "test", "qa", "testing" → "Internal Testing" - Default for bugs → "Internal Testing"

Field Population Priority¶

When syncing to ClickUp, fields are populated in this order (later overrides earlier):

Config defaults (from .beads/integrations/clickup/config.yaml)
Inferred values (from issue content)
Explicit issue values (from issue.custom_fields)

Example:

# Config default
lifecycle_stage:
  default: "High-Level Design & Architecture"

# Issue with type="bug" and status="in_progress"
# Inferred: lifecycle_stage = "Implementation"  (overrides config default)

# Issue with explicit field
custom_fields = {"lifecycle_stage": "Testing & QA"}
# Explicit value takes precedence over inference

CLI Usage¶

Creating Issues with Templates¶

# Create issue with automatic template selection
bd create --title="Fix auth bug" --type=bug

# The description will be pre-populated with the bug template

Validating Descriptions¶

# Validate all issues
bd validate-descriptions

# Validate specific issue
bd validate-descriptions <issue-id>

Customizing Inference Rules¶

Edit beads_clickup/field_inference.py to customize inference logic:

class FieldInferenceEngine:
    # Add custom rules
    LIFECYCLE_STAGE_RULES = {
        "your-keyword": "Your Stage",
        ...
    }

    CATEGORY_RULES = {
        "your-keyword": "Your Category",
        ...
    }

Best Practices¶

Always include an Objective - This is the minimum requirement
Use Definition of Done checklists - Makes progress trackable
Be specific in Plans - Break down work into concrete steps
Update Results when closing - Document what was accomplished
Trust the inference engine - It will populate most fields correctly
Override when needed - Explicit values always take precedence

Examples¶

Well-Structured Issue¶

**Objective:**
Implement rate limiting for API endpoints to prevent abuse

**Plan:**
1. Design rate limiting strategy (token bucket algorithm)
2. Implement middleware for rate limiting
3. Add Redis backend for distributed rate limits
4. Configure limits per endpoint
5. Add monitoring and alerting

**Definition of Done:**
- [ ] Rate limiting middleware implemented
- [ ] Redis integration working
- [ ] All endpoints protected
- [ ] Tests passing
- [ ] Monitoring dashboards updated
- [ ] Documentation updated

**Testing/Evaluation Plan:**
- Unit tests for rate limiting logic
- Integration tests with Redis
- Load testing to verify limits work under stress
- Manual testing of limit reset behavior

**Results:**
TBD

Inferred fields: - lifecycle_stage: "Implementation" (keyword: "implement") - category: "Engineering" (keyword: "api") - effort: "L" (6 checklist items) - value: "High" (implicit from comprehensive plan)

Minimal Valid Issue¶

**Objective:**
Update README with new deployment instructions

Inferred fields: - lifecycle_stage: "Implementation" (type: task) - category: "Documentation" (keyword: "readme") - effort: "S" (simple, no checklist) - value: "Medium" (default for P2)

Troubleshooting¶

Issue Not Following Structure¶

Problem: Old issues without structured format

Solution:

from beads_clickup.issue_template import IssueDescriptionValidator

# Check if structured
if not IssueDescriptionValidator.has_structure(description):
    # Add structure
    structured = IssueDescriptionValidator.format_description(
        objective=description,  # Use old description as objective
        minimal=True
    )

Wrong Field Values¶

Problem: Inference engine chose wrong values

Solution: Set fields explicitly in the issue:

bd update <id> --custom-field lifecycle_stage="Testing & QA"

Or in code:

issue["custom_fields"] = {
    "lifecycle_stage": "Testing & QA",
    "category": "Engineering"
}

ClickBot Still Complaining¶

Problem: Required fields still missing after sync

Check: 1. Are defaults configured in config.yaml? 2. Is the field marked as required: true? 3. Does the field have a default value? 4. Check sync logs for inference output

Debug:

from beads_clickup.field_inference import get_smart_defaults

inferred = get_smart_defaults(issue, config)
print("Inferred fields:", inferred)