othmanadi--planning-with-files/docs/quickstart.md

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:

What Happens	Which File to Update	What to Add
You research something	findings.md	Add to "Research Findings"
You view 2 browser/search results	findings.md	MUST update (2-Action Rule)
You make a technical decision	findings.md	Add to "Technical Decisions" with rationale
You complete a phase	task_plan.md	Change status: in_progress → complete
You complete a phase	progress.md	Log actions taken, files modified
An error occurs	task_plan.md	Add to "Errors Encountered" table
An error occurs	progress.md	Add to "Error Log" with timestamp

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):

   ./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.

The planning files are working memory, not a tracked deliverable: they are gitignored and are not archived automatically. See After Completion: What Happens to the Plan Files for the intended lifecycle and how to keep a completed plan if you want one.

---

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

Don't	Do Instead
Start work without creating task_plan.md	Always create the plan file first
Forget to update findings.md after 2 browser operations	Set a reminder: "2 view/browser ops = update findings.md"
Skip logging errors because you fixed them quickly	Log ALL errors, even ones you resolved immediately
Repeat the same failed action	If something fails, log it and try a different approach
Only update one file	The three files work together - update them as a set

---

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