Tracker Creation Guide (Project Standard)

How to create lightweight progress-tracking documents (“trackers”) that other AI agents and contributors can follow across sessions.

Folder structure (required)

Every project must keep trackers in the following structure:

trackers/
├── readme.md                 # short entrypoint that points to this guide
├── tracker_creation_guide.md # this file (copy from standards into the project)
└── files/                    # all tracker documents live here
    ├── <topic>_tracking.md
    └── ...

Rules:

Trackers must live in trackers/files/.
trackers/readme.md must exist and must point to trackers/tracker_creation_guide.md.

Naming convention

File name: <topic>_tracking.md
- Examples: docs_review_tracking.md, api_refactor_tracking.md, security_audit_tracking.md
Prefer stable, descriptive topic names. Avoid dates in filenames unless multiple trackers exist for the same topic.

When to create a tracker

Create a tracker when work:

Touches multiple modules/files
Spans multiple sessions/prompts
Requires systematic verification (audit/standardization)
Needs explicit “source of truth” for progress and decisions
Is requested by the project lead (“use tracking”, “create a tracker”, etc.)

Required sections (tracker file)

Every tracker in trackers/files/ must include the sections below.

1) Header

Started: YYYY-MM-DD
Owner: person/team/agent
Objective: one sentence describing the goal

2) Ground Rules / Instructions

Agent-readable rules (imperatives). Examples:

Verify every claim against source code.
Do not edit outside a specific directory without approval.
Ask the project lead when behavior is ambiguous.
Do not perform migrations unless explicitly instructed.

3) Workflow

Step-by-step checklist for the standard loop:

Read → verify → propose → implement → validate → update tracker.

4) Progress Tracker

Use one consistent status layout:

### ✅ Completed
- [x] ...

### 🔄 In Progress
- [ ] ...

### ⏳ Pending
- [ ] ...

### 🚫 Out of Scope
- ...

5) Notes & Follow-Ups

Keep a running list of:

blockers
open questions
decisions made and why
“next session start here” hints

Optional sections

Use these when helpful:

Glossary / Links: shortcuts to related docs/templates.
Risks: rollout risks, mitigations.
Validation Plan: how to verify changes (tests, manual checks).
Decision Log: explicit decisions and rationale.

Template skeleton (copy/paste)

# <Tracker Name>

**Started**: YYYY-MM-DD  
**Owner**: <name/team>  
**Objective**: <one-sentence goal>

---

## Ground Rules for Agents
1. ...
2. ...

---

## Workflow
1. ...
2. ...
3. ...

---

## Progress Tracker
### ✅ Completed
- [x] ...

### 🔄 In Progress
- [ ] ...

### ⏳ Pending
- [ ] ...

### 🚫 Out of Scope
- ...

---

## Notes & Follow-Ups
- ...

Deliverable checklist

Before considering a tracker “ready”:

Folder placement matches trackers/files/.
Objective is unambiguous and one sentence.
Rules are explicit and safe-by-default.
Workflow describes “how we will work”.
Progress section is initialized (even if everything is pending).
Notes includes any current blockers or open questions.