Quick Start Guide

Follow these 5 steps to use the planning-with-files pattern.

Step 1: Invoke the Skill and Describe Your Task

When: Before starting any work on a complex task

Action: Invoke the skill (e.g., /plan or /planning-with-files:start) and describe what you want to accomplish. The AI will create all three planning files in your project directory:

• task_plan.md — Phases and progress tracking
• findings.md — Research and discoveries
• progress.md — Session log and test results

If you invoke the skill without a task description, the AI will ask you what you'd like to plan.

Manual alternative: If you prefer to create files yourself:

# Use the init script
./scripts/init-session.sh
# Then fill in the Goal section in task_plan.md

Step 2: Plan Your Phases

When: Right after creating the files

Action: Break your task into 3-7 phases in task_plan.md

Example:

### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Research existing solutions
- **Status:** in_progress

### Phase 2: Implementation
- [ ] Write core code
- **Status:** pending

Update:

• task_plan.md: Define your phases
• progress.md: Note that planning is complete

Step 3: Work and Document

When: Throughout the task

Action: As you work, update files:

Example workflow:

1. Research → Update findings.md
2. Research → Update findings.md (2nd time - MUST update now!)
3. Make decision → Update findings.md "Technical Decisions"
4. Implement code → Update progress.md "Actions taken"
5. Complete phase → Update task_plan.md status to "complete"
6. Complete phase → Update progress.md with phase summary

Optional: Split Large or Unrelated Topics

For one focused task, the three root files are enough. For several unrelated tasks in the same repository, use an isolated plan directory so each topic has its own task_plan.md, findings.md, and progress.md:

./scripts/init-session.sh backend-refactor
./scripts/init-session.sh production-incident
./scripts/set-active-plan.sh 2026-01-10-backend-refactor

For a long-running operational topic that shares the same root plan, keep progress.md concise and move durable details into a topic handoff file:

progress.md
  Runtime-wide timeline and short pointers

handoffs/backend-refactor.md
  Current state, commands, validation, risks, rollback, PR links

Use this pattern when a discussion spans multiple sessions, has many commands, or needs a clean resume point without scanning the full timeline. Add one short line to progress.md whenever the topic handoff changes, then put the details in the handoff file.

For GitHub work, progress.md should usually record only the branch, commit, PR URL, validation summary, and handoff file. Put the longer PR context, remaining risks, and rollback notes in the topic handoff.

Step 4: Re-read Before Decisions

When: Before making major decisions (automatic with hooks in Claude Code)

Action: The PreToolUse hook automatically reads task_plan.md before Write/Edit/Bash operations

Manual reminder (if not using hooks): Before important choices, read task_plan.md to refresh your goals

Why: After many tool calls, original goals can be forgotten. Re-reading brings them back into attention.

Step 5: Complete and Verify

When: When you think the task is done

Action: Verify completion:

1. Check task_plan.md: All phases should have **Status:** complete
2. Check progress.md: All phases should be logged with actions taken
3. Run completion check (if using hooks, this happens automatically):
   bashCopy

   ./scripts/check-complete.sh
   

If not complete: The Stop hook (or script) will prevent stopping. Continue working until all phases are done.

If complete: Deliver your work! All three planning files document your process.

Quick Reference: When to Update Which File

┌─────────────────────────────────────────────────────────┐
│  task_plan.md                                            │
│  Update when:                                            │
│  • Starting task (create it first!)                      │
│  • Completing a phase (change status)                    │
│  • Making a major decision (add to Decisions table)     │
│  • Encountering an error (add to Errors table)          │
│  • Re-reading before decisions (automatic via hook)      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  findings.md                                             │
│  Update when:                                            │
│  • Discovering something new (research, exploration)    │
│  • After 2 view/browser/search operations (2-Action!)   │
│  • Making a technical decision (with rationale)          │
│  • Finding useful resources (URLs, docs)                 │
│  • Viewing images/PDFs (capture as text immediately!)   │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  progress.md                                             │
│  Update when:                                            │
│  • Starting a new phase (log start time)                 │
│  • Completing a phase (log actions, files modified)      │
│  • Running tests (add to Test Results table)            │
│  • Encountering errors (add to Error Log with timestamp)│
│  • Resuming after a break (update 5-Question Check)     │
└─────────────────────────────────────────────────────────┘

Common Mistakes to Avoid

Next Steps

• See examples/README.md for complete walkthrough examples
• See workflow.md for the visual workflow diagram
• See troubleshooting.md if you encounter issues