plan

# File-Based Task Plan Template ## Repo Tweaks (tck-gfql) - Default local validation in this repo: `./bin/ci.sh`, `pytest tests/cypher_tck -xvs`, and `python -m tests.cypher_tck.report`. - Keep plan files under `plans/<task>/` (already gitignored here). ## Default: Use Your Platform's Native Planning **For single-session work, prefer your AI platform's built-in planning features.** This file-based approach adds overhead that's only justified for specific scenarios. ## When to Use THIS Skill (Opt-In) Only use this file-based plan template when: - **User explicitly requests it** ("use the plan template", "create a plan file") - **Work spans multiple sessions** and must survive context resets - **Handoff to another AI/human** who needs full written context - **Complex multi-PR coordination** requiring persistent state ## Setup 1. Copy this template to `plans/[task_name]/plan.md` 2. Replace all `[placeholders]` with actual values 3. Fill out Context sections completely 4. Start with Step 1 marked as IN_PROGRESS ## Critical Meta-Goals **THIS PLAN MUST BE:** 1. **FULLY SELF-DESCRIBING**: All context needed to resume work is IN THIS FILE 2. **CONSTANTLY UPDATED**: Every action's results recorded IMMEDIATELY in the step 3. **THE SINGLE SOURCE OF TRUTH**: If it's not in the plan, it didn't happen 4. **SAFE TO RESUME**: Any AI can pick up work by reading ONLY this file **REMEMBER**: External memory is unreliable. This plan is your ONLY memory. ## Anti-Drift Protocol ### The Three Commandments 1. **RELOAD BEFORE EVERY ACTION**: Your memory has been wiped. This plan is all you have. 2. **UPDATE AFTER EVERY ACTION**: If you don't write it down, it never happened. 3. **TRUST ONLY THE PLAN**: Not your memory, not your assumptions, ONLY what's written here. ### Critical Rules - **ONE TASK AT A TIME** - Never jump ahead - **NO ASSUMPTIONS** - The plan is the only truth - **NO OFFROADING** - If it's not in the plan, don't do it ### Step Execution Protocol **BEFORE EVERY SINGLE ACTION:** 1. **RELOAD PLAN**: `cat plans/[task_name]/plan.md | head -200` 2. **FIND YOUR TASK**: Locate the current IN_PROGRESS step 3. **EXECUTE**: ONLY do what that step says 4. **UPDATE IMMEDIATELY**: Edit this plan with results BEFORE doing anything else 5. **VERIFY**: `tail -50 plans/[task_name]/plan.md` ### If Confused 1. STOP 2. Reload this plan 3. Find the last completed step 4. Continue from there ## Plan Template ```markdown # [Task Name] Plan **THIS PLAN FILE**: `plans/[task_name]/plan.md` **Created**: [DATE TIME TIMEZONE] **Current Branch**: [from `git branch --show-current`] **PRs**: [PR number + title + plan role] **PR Target Branch**: [where this will merge] **Base branch**: [FILL ME IN, TYPICALLY PR TARGET BRANCH] ## Context (READ-ONLY) ### Plan Overview **Raw Prompt**: [What the user said, verbatim] **Goal**: [What we're trying to achieve] **Description**: [Brief description of the task] **Success Criteria**: [How we know we're done] **Key Constraints**: [Important limitations or requirements] ### Technical Context **Initial State**: - Working Directory: [pwd output] - Current Branch: `[branch-name]` (forked from `[parent]` at `[SHA]`) - Target Branch: `[where this merges to]` ### Strategy **Approach**: [High-level plan] **Key Decisions**: - [Decision 1]: [Reasoning] - [Decision 2]: [Reasoning] ## Quick Reference ```bash # Reload plan cat plans/[task_name]/plan.md | head -200 # Local validation before pushing ./bin/ci.sh pytest tests/cypher_tck -xvs python -m tests.cypher_tck.report # CI monitoring gh pr checks [PR] --watch ``` ## Status Legend - TODO: Not started - IN_PROGRESS: Currently working on this - DONE: Completed successfully - FAILED: Failed, needs retry - SKIPPED: Not needed - BLOCKED: Can't proceed ## LIVE PLAN ### Steps #### Step 1: [Description] **Status**: IN_PROGRESS **Action**: [What to do] **Success Criteria**: [How to verify] **Result**: ``` [Fill in with commands, output, decisions, errors] ``` #### Step 2: [Description] **Status**: TODO **Action**: [What to do] **Success Criteria**: [How to verify] ``` ## Step Compaction **Every ~30 completed steps, compact the plan:** 1. Create history file: `plans/[task_name]/history/steps<start>-to-<end>.md` 2. Replace archived steps with summary in plan 3. Continue with next step number