Plan

Purpose

Turn a ticket, feature request, or rough idea into a plan that is clear enough to implement against.

For smaller work, that means a short working plan.

For larger multi-hour work, that means a longer living execution plan in the style of PLANS.md.

When to use

• Starting a new feature or meaningful change
• A Linear ticket is good, but still needs cleaner implementation intent
• Requirements, scope, or success criteria are unclear
• The change touches multiple files, interfaces, config, schema, or data flow
• The task is large enough that you want a document to guide several implementation passes

Choose the right level of planning

1. Lightweight plan

Use this when:

• the ticket is already fairly descriptive
• the change is small or medium
• you mainly need clearer scope, steps, and verification

Output:

• a short Markdown plan
• usually 5-20 lines
• enough for one focused implementation session

2. Full execution plan

Use this when:

• the task may take multiple hours
• the work spans multiple milestones
• you need a living document during implementation
• another engineer or agent should be able to continue from the plan alone

Output:

• a self-contained plan in the style of PLANS.md
• prose-first, explicit, and updateable during implementation

Process

1. Read the ticket, product context, AGENTS.md, and relevant code before planning.
2. Restate the goal in plain English.
3. Decide whether this needs a lightweight plan or a full execution plan.
4. If a material decision is missing, ask a concise question or state an explicit assumption.
5. Write the plan so someone could implement from it without relying on hidden context.

What a lightweight plan should contain

• Goal
• Context
• Scope
• Non-goals
• Proposed steps
• Risks
• Verification

Example:

# GRA-141 Plan

Goal: persist scraped jobs into Postgres while keeping CSV export.

Context:
- Current scraper exports CSV.
- We want minimal persistence without broadening scope into UI or API work.

Scope:
- Add DB configuration.
- Define a minimal jobs table.
- Persist jobs from the scraper flow.

Non-goals:
- No new UI.
- No API endpoints.
- No broad data model redesign.

Steps:
1. Add DB configuration and connection setup.
2. Define minimal `jobs` table.
3. Implement job upsert logic.
4. Wire scraper CLI to persist jobs.
5. Keep CSV export optional.
6. Add tests for upsert and rerun behavior.
7. Run review and cleanup.

Verification:
- Targeted tests pass.
- Existing CLI flow still works.

What a full execution plan should contain

A full execution plan should be self-contained and readable by someone with only the working tree and the plan.

Required sections:

• Purpose
• Progress
• Surprises & Discoveries
• Decision Log
• Outcomes & Retrospective
• Context and Orientation
• Plan of Work
• Concrete Steps
• Validation and Acceptance
• Rollback or Safety Notes, if relevant

For larger tasks:

• write in plain English
• explain non-obvious terms immediately
• name files by path
• keep the plan updated as work progresses

Rules

• Keep the plan as short as the task allows.
• Do not write a greenfield design if the codebase already has patterns to follow.
• Call out schema, config, CLI, API, or file-format changes explicitly.
• Make requirements specific enough that someone can review the implementation against them.
• If the request is tiny and obvious, skip the long plan and move straight to a lightweight plan or direct implementation.
• If the task is long-running, treat the plan as a living document and update it during execution.
• If the plan starts getting large because the task is actually several tasks, split the work.

Resources

For this repo, use:

• resources/plan-template.md for a short working plan
• resources/execplan-template.md for a longer PLANS.md-style execution plan