progress-tracking

# 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: 1. **Previous work completed** on this and other tasks 2. **Codebase patterns and learnings** from previous iterations 3. **The Codebase Patterns section** (at the top) contains reusable patterns and guardrails 4. **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`: 1. **Read the last 10–20 lines** to get exact trailing content and structure. 2. **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. 3. **After two failed replace attempts**, switch to shell append: `echo '...' >> tasks/progress.txt` instead of further edits. 4. 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 1. **After major milestones:** Document significant progress 2. **When patterns are discovered:** Capture reusable insights 3. **Before task completion:** Ensure all learnings are recorded 4. **When encountering issues:** Document problems and solutions ### What to Document 1. **Implementation details:** What was built and how 2. **Files changed:** Track which files were modified 3. **Learnings:** Patterns, gotchas, and useful context 4. **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 ```