besync-labs Plan Writing
Small tasks, clear outcomes, verifiable results.
Overview
Framework for breaking down work into clear, actionable tasks with verification criteria.
Task Breakdown Principles
1. Small, Focused Tasks
- Each task: 2-5 minutes
- One clear outcome per task
- Independently verifiable
2. Clear Verification
- How do you know it's done?
- What can you check/test?
- What's the expected output?
3. Logical Ordering
- Dependencies identified
- Parallel work where possible
- Critical path highlighted
- Verification is always LAST
Planning Principles
🔴 NO fixed templates. Each plan's CONTENT is UNIQUE to the task. ✅ Every plan MUST satisfy the quality schema in
plan-schema.md. Dynamic content within a consistent structure = the standard.
Principle 1: Right-Size to Task Tier
Plan length MUST match task complexity:
| Task Tier | Max Sections | Max Tasks | Guideline |
|---|---|---|---|
| Trivial (1-2 files) | Tier 1 only (7 sections) | 5-8 tasks | ~1 page — concise, no specialist synthesis |
| Medium (3-10 files) | Tier 1 + Tier 2 (15 sections) | 8-15 tasks | 2-3 pages — includes specialist input |
| Large (10+ files) | Tier 1 + Tier 2 + domains (15+ sections) | 15-25 tasks | 3-5 pages — full multi-agent synthesis |
| ❌ Wrong | ✅ Right |
|---|---|
| 50 tasks with sub-sub-tasks | Right-sized task count per tier |
| Every micro-step listed | Only actionable items |
| Verbose descriptions | One-line per task |
| Large task crammed into 1 page | Large task gets full Tier 2 coverage |
| Trivial task with 15 sections | Trivial task uses Tier 1 only |
Rule: Trivial tasks stay concise (~1 page). Medium/Large tasks expand to cover all required tier sections. Never sacrifice completeness for brevity on complex tasks.
Principle 2: Be SPECIFIC, Not Generic
| ❌ Wrong | ✅ Right |
|---|---|
| "Set up project" | "Run npx create-next-app" |
| "Add authentication" | "Install next-auth, create /api/auth/[...nextauth].ts" |
| "Style the UI" | "Add Tailwind classes to Header.tsx" |
Principle 3: Dynamic Content Based on Context
For NEW PROJECT:
- What tech stack?
- What's the MVP?
- What's the file structure?
For FEATURE ADDITION:
- Which files are affected?
- What dependencies needed?
- How to verify it works?
For BUG FIX:
- What's the root cause?
- What file/line to change?
- How to test the fix?
Principle 4: Verification is Simple
| ❌ Wrong | ✅ Right |
|---|---|
| "Verify the component works" | "Run npm run dev, click button, see toast" |
| "Test the API" | "curl localhost:3000/api/users returns 200" |
| "Check styles" | "Open browser, verify dark mode works" |
Principle 5: Cross-Cutting Concerns Are Mandatory
Every plan MUST explicitly address:
- Security: Reference
.agent/rules/security.md— what security implications exist? - Testing: Reference
.agent/rules/testing.md— what test types are needed? Coverage targets? - Documentation: Reference
.agent/rules/documentation.md— which docs need updating?
If a concern is genuinely not applicable, state N/A — [one-line justification].
NEVER silently omit these sections. Silent omission is a plan defect.
Principle 6: Schema Compliance
Every plan MUST satisfy the quality schema defined in plan-schema.md:
- Tier 1 sections are ALWAYS required. Omitting any Tier 1 section is a plan defect.
- Tier 2 sections are required for Medium and Large tasks (3+ files or 1+ hours).
- Before presenting a plan, validate it against the schema checklist.
- Plans scoring below 70% of their tier maximum must be revised before presentation.
See also: domain-enhancers.md for domain-specific plan sections.
Plan Structure (Minimal)
# [Task Name]
## Goal
One sentence: What are we building/fixing?
## Tasks
- [ ] Task 1: [Action] → Verify: [Check]
- [ ] Task 2: [Action] → Verify: [Check]
- [ ] Task 3: [Action] → Verify: [Check]
## Done When
- [ ] [Main success criteria]
## Notes
[Any important considerations]
That's it. No phases, no sub-sections unless truly needed.
Best Practices
- Start with goal — What are we building/fixing?
- Max 10 tasks — If more, break into multiple plans
- Each task verifiable — Clear "done" criteria
- Project-specific — No copy-paste templates
- Update as you go — Mark
[x]when complete
When to Use
- New project from scratch
- Adding a feature
- Fixing a bug (if complex)
- Refactoring multiple files