name	progress-tracking
description	Format and structure for progress.txt files, documenting learnings, managing Codebase Patterns section, and when to update progress. Use when documenting work progress, learnings, or codebase patterns.

Progress Tracking

This skill provides comprehensive guidance on managing tasks/progress.txt files, including format, structure, learnings documentation, and Codebase Patterns management.

Overview

The tasks/progress.txt file serves as:

A log of completed work across tasks
A repository of reusable patterns and learnings
A reference for codebase-specific best practices
A guardrail system for common pitfalls

Reading Progress Files

Essential Reading Workflow

When starting a task, always read tasks/progress.txt to understand:

Previous work completed on this and other tasks
Codebase patterns and learnings from previous iterations
The Codebase Patterns section (at the top) contains reusable patterns and guardrails
Task-specific entries show what was done in previous iterations

Codebase Patterns Section

CRITICAL: Check the "Codebase Patterns" section first when reading tasks/progress.txt:

Reusable patterns discovered in previous work
Common gotchas and how to avoid them
Best practices specific to this codebase
Guardrails and constraints

This section is maintained at the top of the file and contains patterns that apply across all tasks.

Progress.txt Format

Update Requirements

Update progress.txt incrementally:

After major milestones
When patterns are discovered
Before task completion

Document Learnings

Use "Learnings for future iterations:" section:

Include codebase patterns discovered
Document successful approaches
Note common pitfalls
Capture reusable insights

Success Criteria Validation

Explicitly verify each success criterion:

Document verification method used
Update progress before completion marker
Include evidence of completion

Progress file update (appending to tasks/progress.txt)

When appending a new task block to tasks/progress.txt:

Read the last 10–20 lines to get exact trailing content and structure.
Use a unique anchor for search_replace (e.g. task ID and date: ## YYYY-MM-DD - Task TASK_ID). Do not replace on generic separators like --- alone.
After two failed replace attempts, switch to shell append: echo '...' >> tasks/progress.txt instead of further edits.
Optionally: reuse recent grep results when the query is unchanged to avoid redundant searches.

Entry Format

When you complete work or learn something, append to tasks/progress.txt:

## [Date/Time] - Task {id}
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Pattern discovered
  - Gotcha encountered
  - Useful context
---

Codebase Patterns Management

Adding to Codebase Patterns

If you discover a reusable pattern that should be available for all future tasks, add it to the "Codebase Patterns" section at the top of the file.

When to add:

Pattern is reusable across multiple tasks
Pattern prevents common errors
Pattern represents a codebase-specific best practice
Pattern documents a constraint or guardrail

Format for Codebase Patterns:

# Codebase Patterns

## Pattern Name
- Description of pattern
- When to use it
- Example usage
- Common pitfalls to avoid

Maintaining Codebase Patterns

Keep patterns concise and actionable
Update patterns when they evolve
Remove outdated patterns
Group related patterns together

Progress Documentation Best Practices

When to Document

After major milestones: Document significant progress
When patterns are discovered: Capture reusable insights
Before task completion: Ensure all learnings are recorded
When encountering issues: Document problems and solutions

What to Document

Implementation details: What was built and how
Files changed: Track which files were modified
Learnings: Patterns, gotchas, and useful context
Verification: How success criteria were validated

Progress Update Checklist

Before completing a task, verify:

✅ Major milestones documented
✅ Learnings captured in "Learnings for future iterations:" section
✅ Codebase patterns added if applicable
✅ Success criteria validation documented
✅ Files changed are listed
✅ Verification method is recorded

Integration with Other Skills

This skill works with:

task-verification-workflow: Document verification methods
error-recovery-patterns: Document error handling learnings
completion-marker-optimization: Update progress before completion marker

Examples

Example Entry

## 2026-01-27 14:30 - Task 42
- Implemented user authentication flow
- Files changed: src/auth.ts, src/components/Login.tsx
- **Learnings for future iterations:**
  - Use JWT tokens stored in httpOnly cookies for security
  - Always validate tokens server-side before processing requests
  - Pattern: Authentication middleware should check token expiry
---

Example Codebase Pattern

# Codebase Patterns

## Authentication Pattern
- Always use httpOnly cookies for JWT tokens
- Validate tokens server-side in middleware
- Check token expiry before processing requests
- Never expose tokens in client-side JavaScript

progress-tracking