Skip to content

Reconcile tasks/todo.md format with global EXECUTION_TEMPLATES standard #158

Description

@markcallen

Problem

Ballast's common/tasks-todo.md and typescript/typescript-tasks-todo.md rules define tasks/TODO.md as a simple markdown checklist:

# TODO

- [ ] Add input validation to the config parser
- [x] Write tests for the new agent content path

The global AGENTS.md / EXECUTION_TEMPLATES.md framework (used across all repos) defines tasks/todo.md as a structured template with full task lifecycle metadata. These two formats are incompatible:

  • Different capitalization (TODO.md vs todo.md)
  • Different structure (flat checklist vs structured sections)
  • Ballast's version is described as "branch-scoped scratchpad / working memory"; the global version is a planning artifact with scope, constraints, test strategy, and rollback strategy

An agent working in a Ballast-managed repo with the global framework loaded will produce conflicting artifacts depending on which rule it reads first.

Proposed Resolution

The Ballast tasks-todo rule should align with the global EXECUTION_TEMPLATES.md standard. The file should be tasks/todo.md (lowercase) and use the structured template below, which comes from EXECUTION_TEMPLATES.md.

The lightweight "scratchpad" use case can be preserved by noting that simple tasks may omit optional sections — but the format and filename should be canonical.

EXECUTION_TEMPLATES.md Reference

The following is the authoritative tasks/todo.md template from the global execution framework:

# Task: <title>

## Context
- Owner:
- Date:
- Mode: <Autonomous|Approval-Required>
- PRD Section:
- Requirement IDs:

## Scope
- In scope:
- Out of scope:

## Acceptance Criteria
- AC1:
- AC2:

## Constraints
- Constraint 1

## Risks and Tradeoffs
- Risk:
- Tradeoff:

## Execution Checklist
- [ ] Step 1 with observable outcome
- [ ] Step 2 with observable outcome

## Test Strategy
- Unit:
- Integration:
- E2E:
- Failure-path tests:
- Requirement-to-test mapping:

## Rollback Strategy
- Trigger:
- Rollback steps:
- Validation after rollback:

## Outcome
- Result:
- Evidence links/commands:
- PRD updates:

The full EXECUTION_TEMPLATES.md also defines:

Issue output format:

### Issue #N: <Short Description>

**Severity:** <Critical|High|Medium|Low>
**User Impact:** <who is affected and how>
**Likelihood:** <High|Medium|Low>
**Time Sensitivity:** <Immediate|This sprint|Backlog>

**Problem**
Concrete explanation with file/line references and example behavior.

**Option A (Recommended)**
- Effort:
- Risk:
- Code Impact:
- Maintenance:

**Option B**
- Effort:
- Risk:
- Code Impact:
- Maintenance:

**Option C (Optional / Do Nothing)**
- Effort:
- Risk:
- Code Impact:
- Maintenance:

**Recommendation**
Explain why Option A is best based on correctness, risk, testability, and maintenance.

**Decision Request**
Proceed with: A (recommended), B, C, or alternate direction?

tasks/lessons.md template:

# Lessons

## <YYYY-MM-DD> <Short Title>
- Incident/bug:
- Root cause pattern:
- Early signal missed:
- Preventative rule:
- Validation added (test/check/alert):
- Next trigger to detect sooner:

Acceptance Criteria

  • tasks/todo.md filename is standardised to lowercase across all Ballast rules
  • The tasks-todo rule references the structured template (with optional sections for lightweight use)
  • A new tasks-templates or tasks-execution rule (or update to tasks-todo) ships the canonical templates for tasks/todo.md, tasks/lessons.md, and issue output format
  • The rule clearly states that simple scratchpad items can use a subset of the template but must not use a different format

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions