# Cursor Planning Templates & Examples


**Last Updated:** 2025-11-20

This document provides concrete examples of good vs bad plans, plus templates for different task types to guide comprehensive planning.

## Plan Quality Examples

### Example 1: GOOD Comprehensive Plan

**Task:** "Update the FAQ section in compare_planday.php to include a question about pricing"

**Plan:**

**Discovery Phase:**

1. Read `v2/pages/compare_planday.php` lines 450-550 (existing FAQ section)
2. Check other comparison pages for FAQ pricing patterns (grep "Kosten" v2/pages/compare\_\*.php)
3. Verify current Ordio pricing (€89/Standort/Monat standard)
4. Review Planday pricing from their website (research current rates)

**Implementation Phase:**

1. Add new FAQ item to compare_planday.php after line 485 (before closing FAQ section)
2. Use existing FAQ pattern (`<details>` + `<summary>` structure)
3. Question: "Was kostet Planday im Vergleich zu Ordio?"
4. Answer (150-200 words): Start with Planday pricing, transition to Ordio pricing, explain value difference
5. Mention Ordio naturally once in answer

**Validation Phase:**

1. Load page locally: http://localhost:8003/v2/pages/compare_planday.php
2. Verify FAQ toggle works (`<details>` element)
3. Check FAQPage schema includes new item (use Google Rich Results Test)
4. Visual inspection: FAQ formatting matches other items
5. Test mobile layout (FAQ readable on small screens)

**Risks & Rollback:**

- Risk: Planday pricing outdated → Mitigation: Research current pricing before writing
- Risk: FAQ schema breaks → Mitigation: Validate schema after adding
- Rollback: Revert file with git if schema validation fails

**Handoff:**

- Added 1 FAQ item to compare_planday.php (line 486-495)
- Verified FAQ toggle and schema validation
- Ready for review and deployment

**Why this is GOOD:**

- ✅ Specific file path and line range
- ✅ Research step included (check other pages, verify pricing)
- ✅ Concrete implementation steps with pattern to follow
- ✅ Comprehensive validation (local test, schema, visual, mobile)
- ✅ Risks identified with mitigation
- ✅ Clear handoff summary

---

### Example 2: BAD Vague Plan

**Task:** "Update the FAQ section in compare_planday.php to include a question about pricing"

**Plan:**

1. Open the comparison page
2. Add a new FAQ about pricing
3. Test it

**Why this is BAD:**

- ❌ No file path or line range specified
- ❌ No research step (existing patterns, pricing verification)
- ❌ No specific implementation details (what question? what answer?)
- ❌ Vague validation ("test it" - how? what to check?)
- ❌ No risk assessment or rollback plan
- ❌ No handoff summary

**This plan would force the agent to guess or ask follow-up questions instead of proceeding with confidence.**

---

### Example 3: GOOD Simple Task Plan

**Task:** "Fix typo in product_schichtplan.php hero headline (change 'erstellst' to 'erstelltst')"

**Plan:**

**Discovery Phase:**

1. Read `v2/pages/product_schichtplan.php` lines 1-100 (locate hero headline)
2. Verify typo exists (expected on line ~65)

**Implementation Phase:**

1. search_replace in v2/pages/product_schichtplan.php
2. old_string: "erstellst du Dienstpläne"
3. new_string: "erstelltst du Dienstpläne" (wait, this creates a NEW typo!)

**STOP:** This is wrong. The task says "change 'erstellst' to 'erstelltst'" but 'erstelltst' is incorrect German.

**Clarification needed:** User likely meant "fix typo 'erstelltst' to 'erstellst'" (correct the existing typo).

**Revised Plan:**

**Discovery Phase:**

1. Read `v2/pages/product_schichtplan.php` hero section (lines 50-80)
2. Locate typo 'erstelltst' (should be 'erstellst')

**Implementation Phase:**

1. search_replace in v2/pages/product_schichtplan.php
2. old_string: "erstelltst du Dienstpläne"
3. new_string: "erstellst du Dienstpläne"

**Validation Phase:**

1. Read updated file to confirm fix
2. Load page locally, visual check hero headline

**Handoff:**

- Fixed typo in product_schichtplan.php line 65
- Hero headline now reads correctly: "erstellst du Dienstpläne"

**Why this is GOOD (even for simple task):**

- ✅ Caught potential error (misunderstood task)
- ✅ Asked for clarification instead of guessing
- ✅ Specific file, line range, and exact strings
- ✅ Simple but complete validation (read file, visual check)
- ✅ Appropriate detail level for simple task

---

## Planning Templates

### Template 1: New Feature Implementation

```markdown
## Task: [Feature Name]

### Discovery Phase

**Understand Requirements:**

- [ ] Read task description completely
- [ ] Identify all affected files (list expected files)
- [ ] Research similar features in codebase (use codebase_search, grep)
- [ ] Review related documentation (docs/, .cursor/rules/, guides/)
- [ ] Identify dependencies (what other systems interact with this?)

**Research Existing Patterns:**

- [ ] Find similar implementations: [search query]
- [ ] Read reference files: [list files]
- [ ] Document patterns to reuse: [note patterns]

**Clarifying Questions (if any):**

- [ ] [Question 1]
- [ ] [Question 2]

### Implementation Phase

**Step 1: [First Major Step]**

- File: [exact path]
- Action: [specific change]
- Tool: [tool to use: read_file, search_replace, write, etc.]
- Dependency: [what must be done first]

**Step 2: [Second Major Step]**

- ...

**Step N: [Final Step]**

- ...

### Validation Phase

**Functional Testing:**

- [ ] Test with valid inputs: [describe]
- [ ] Test with invalid inputs: [describe]
- [ ] Test edge cases: [describe]

**Integration Testing:**

- [ ] Verify interactions with [system X]
- [ ] Check [API endpoint / database / etc.]
- [ ] Test on [page types / browsers / devices]

**Code Quality:**

- [ ] No console errors
- [ ] No linter errors (run read_lints on changed files)
- [ ] Follows existing code patterns

**Performance:**

- [ ] No performance regressions (if applicable)
- [ ] Images optimized (if applicable)
- [ ] Caching works (if applicable)

### Risks & Rollback

**Potential Risks:**

1. [Risk 1]: [Description] → Mitigation: [How to prevent/handle]
2. [Risk 2]: [Description] → Mitigation: [How to prevent/handle]

**Rollback Plan:**

- If [condition], revert files: [list files]
- If [condition], restore from backup: [describe]

### Handoff

**Deliverables:**

- [List what was created/modified]

**Testing Completed:**

- [Summary of tests run and results]

**Next Steps:**

- [What user or other developer needs to do]

**Documentation Updates Needed:**

- [List docs to update, if any]
```

---

### Template 2: Page Content Update

```markdown
## Task: [Update Description]

### Discovery Phase

**Read Current Content:**

- [ ] Read [file path] [section/line range]
- [ ] Identify target section: [section name]

**Research Patterns:**

- [ ] Check similar pages for copy patterns: [pages]
- [ ] Verify current data (pricing, dates, etc.): [sources]
- [ ] Review schema requirements: [schema types]

### Implementation Phase

**Update Content:**

- File: [exact path]
- Section: [lines X-Y or section name]
- Tool: search_replace or block replacement
- Changes:
  - [Specific change 1]
  - [Specific change 2]

**Update Schema (if applicable):**

- File: [exact path]
- Schema type: [WebPage, Product, etc.]
- Fields to update: [list fields]

**Update Meta Tags (if applicable):**

- Title: [new title]
- Description: [new description]

### Validation Phase

- [ ] Load page locally: http://localhost:8003/[page-path]
- [ ] Visual inspection: [what to check]
- [ ] Schema validation: [use Google Rich Results Test]
- [ ] Meta tags check: [view page source]
- [ ] Du tone verified (informal, benefit-driven)
- [ ] Ordio mentioned naturally (once per major section)

### Handoff

**Updated:**

- [Section/content description]
- [Files modified with line ranges]

**Verified:**

- [What was checked]
```

---

### Template 3: Bug Fix / Refactor

```markdown
## Task: [Bug/Refactor Description]

### Discovery Phase

**Reproduce Issue:**

- [ ] Steps to reproduce: [list steps]
- [ ] Expected behavior: [describe]
- [ ] Actual behavior: [describe]
- [ ] Error messages / console output: [copy errors]

**Root Cause Analysis:**

- [ ] Read affected files: [list files]
- [ ] Identify root cause: [describe cause]
- [ ] Check for similar issues elsewhere: [search codebase]

**Research Solution:**

- [ ] Review existing fix patterns: [describe]
- [ ] Check documentation: [relevant docs]
- [ ] Verify solution approach: [describe approach]

### Implementation Phase

**Fix Issue:**

- File: [exact path]
- Function/Section: [name and line range]
- Change: [specific fix]
- Tool: [tool to use]

**Test Fix:**

- [ ] Reproduce original issue (should not occur after fix)
- [ ] Test related functionality (ensure no regression)
- [ ] Check edge cases: [describe]

### Validation Phase

- [ ] Original issue resolved
- [ ] No regressions in related functionality
- [ ] No new console errors
- [ ] No new linter errors

### Handoff

**Fixed:**

- [Issue description]
- [Root cause]
- [Solution applied]

**Tested:**

- [Tests performed and results]
```

---

### Template 4: Schema / SEO Update

```markdown
## Task: [Schema/SEO Update Description]

### Discovery Phase

**Current State:**

- [ ] Read current schema: [file path, lines]
- [ ] Read current meta tags: [file path, lines]
- [ ] Identify schema type(s): [list types]

**Requirements:**

- [ ] New schema fields needed: [list]
- [ ] New meta tag values: [list]
- [ ] URLs to update: [list]
- [ ] Dates to update (current year): [list]

**Research:**

- [ ] Check schema.org specs for [schema type]
- [ ] Review similar schemas in codebase: [files]
- [ ] Verify current data (pricing, ratings, etc.): [sources]

### Implementation Phase

**Update Schema:**

- File: [exact path]
- Schema type: [e.g., SoftwareApplication]
- Fields to update:
  - [field 1]: [old value] → [new value]
  - [field 2]: [old value] → [new value]

**Update Meta Tags:**

- Title: [new title] (max 60 chars, includes year, keyword, "Ordio")
- Description: [new description] (155-160 chars, du tone, benefit-driven)
- Canonical: [URL]
- OG tags: [list changes]

### Validation Phase

- [ ] Schema validates: Copy JSON-LD into Google Rich Results Test
- [ ] All required fields present for schema type
- [ ] URLs absolute and correct
- [ ] Dates current (2025)
- [ ] Pricing up-to-date (€89/Standort/Monat)
- [ ] Meta tags within character limits
- [ ] Page loads without errors

### Handoff

**Updated:**

- Schema: [type and fields]
- Meta tags: [which tags]

**Verified:**

- Schema validates with Google Rich Results Test
- All URLs and dates current
```

---

## Task Classification Decision Tree

Use this to determine planning depth:

```
START: What type of task is this?
│
├─ NEW FEATURE or UNFAMILIAR CODE?
│  └─ Research-Heavy → Use Template 1 (deep analysis, extensive research)
│
├─ CONTENT UPDATE or SCHEMA CHANGE?
│  └─ Implementation-Heavy → Use Template 2 or 4 (comprehensive but faster)
│
├─ BUG FIX or TYPO CORRECTION?
│  └─ Maintenance → Use Template 3 (streamlined, focused on fix)
│
└─ UNSURE?
   └─ Default to Research-Heavy (better to over-plan than under-plan)
```

---

## Planning Quality Checklist

Before proceeding to implementation, verify your plan:

- [ ] **Specific:** Contains exact file paths, function names, line ranges
- [ ] **Comprehensive:** Covers discovery, implementation, validation, risks
- [ ] **Researched:** References existing code patterns, not assumptions
- [ ] **Actionable:** Clear steps with tools specified
- [ ] **Validated:** Includes test steps and expected outcomes

**If any checkbox is unchecked, revise plan before proceeding.**

---

## When to Ask Clarifying Questions

**Ask when:**

- Task requirements ambiguous or unclear
- Multiple valid approaches with significantly different trade-offs
- User intent uncertain (e.g., "update page" without specifying what to update)
- Potentially destructive action (e.g., deleting files, changing base components)

**Don't ask when:**

- Answer is findable through code reading (use codebase_search, grep, read_file)
- Pattern exists in codebase (research and reuse)
- Standard operation (e.g., "add FAQ" when FAQ pattern is established)

**Format questions:**

- Concise (≤200 chars each)
- Lettered multiple choice when possible
- First option should be default assumption

---

## Examples of Research-First Approach

### Scenario: "Add validation to a form"

❌ **BAD (Guessing):**
"I'll add `required` attribute and email regex validation."

✅ **GOOD (Research-First):**

1. grep "validation" v2/api/\*.php → Find existing validation patterns
2. Read 2-3 API endpoints → Understand standard approach
3. Reuse pattern: `filter_var($email, FILTER_VALIDATE_EMAIL)` + sanitization

### Scenario: "Update pricing schema"

❌ **BAD (Guessing):**
"I'll set price to €99."

✅ **GOOD (Research-First):**

1. grep "price._89" v2/pages/_.php → Find current pricing references
2. Read product pages → Confirm standard is €89/Standort/Monat
3. Check if task specifies new pricing → If not, use €89 (current standard)

---

By following these templates and examples, you'll create comprehensive, actionable plans that enable confident implementation and thorough validation.