synthesys-lab/plan-guideline

Make a Plan

This skill instructs AI agents on how to create comprehensive implementation plans for new features, refactoring, or bug fixes. The plan should be thorough enough to serve as a blueprint for implementation, with concrete file-level details and quantified complexity estimates.

Planning Philosophy

A good plan is:

• Concrete: Specifies exact files to modify/create, not vague "audit the codebase" steps
• Quantified: Uses lines of code instead of time estimates
• Design-first TDD: Follows strict ordering: Documentation → Tests → Implementation
• Interface-driven: Documents API/interface changes before implementation
• Actionable: Can be directly used to create a GitHub issue with open-issue skill

Development Workflow Order

CRITICAL: All implementation plans MUST follow this strict ordering:

1. Documentation first - Update all relevant documentation and design documents
2. Tests second - Write or update test cases that verify the behavior
3. Implementation last - Write the actual implementation code

This design-first test-driven development (TDD) style ensures:

• Clear design before coding
• Testable requirements
• No implementation without tests
• Living documentation that stays in sync

Inputs

The plan-guideline skill takes the following inputs:

• User's goal or requirement (either from conversation or a markdown file)
• Current codebase context (will be explored by the agent)
• Existing architecture patterns and conventions

Planning Process

The AI agent MUST follow this systematic process when creating a plan:

1. Goal Understanding Phase

Objective: Deeply understand what the user wants to achieve.

Actions:

• Read and analyze the user's requirements thoroughly
• Identify the core problem or feature request
• Clarify ambiguous requirements using AskUserQuestion if needed
• Determine the scope: is this a new feature, bug fix, refactoring, or improvement?

Output signals:

• Clear problem statement in 1-2 sentences
• Success criteria (what does "done" look like?)
• Out of scope items (what are we explicitly NOT doing?)

2. Codebase Audit Phase

Objective: Thoroughly explore the codebase to understand current implementation.

CRITICAL: The audit happens DURING planning, not as a step IN the plan. The plan must contain audit RESULTS, not "TODO: audit the codebase" steps.

Actions:

• Use Glob to find relevant files by pattern
• Use Grep to search for related functionality
• Read existing implementations of similar features
• Identify architectural patterns and conventions
• Map out dependencies between modules

Output from this phase:

• List of files that will be modified (with line ranges if possible)
• List of files that will be created (with purpose)
• List of files that may be deleted
• Current architecture understanding

Example of GOOD audit results in plan:

Files to modify:
- `claude/skills/commit-msg/SKILL.md:15-45` - Add milestone commit logic
- `tests/test_git_commit.sh:23-67` - Update test cases for milestones

Files to create:
- `docs/milestone-workflow.md` - Document milestone commit process

Example of BAD (do not include this):

1. Audit the codebase to find relevant files
2. Determine which files need changes

3. Interface Design Phase

Objective: Design the public interfaces, APIs, and documentation changes.

Actions:

• Design new function/class signatures
• Plan changes to existing interfaces (breaking vs. non-breaking)
• Identify documentation files that need updates
• Design configuration or input formats if applicable
• Consider backward compatibility

Output:

• New interfaces to be created (with signatures)
• Modified interfaces (showing before/after)
• Documentation structure (what goes in which doc file)
• Configuration schema if applicable

Example:

New interfaces:
- Function: `create_milestone_commit(files: list, message: str, test_status: str)`
- Config: Add `milestone.allow_no_verify` to project settings

Modified interfaces:
- Function: `git_commit()` - add optional parameter `is_milestone: bool = False`

Documentation updates:
- `docs/git-msg-tags.md:15-20` - Add milestone tag explanation
- `claude/skills/commit-msg/SKILL.md:40-60` - Add milestone section

4. Test Strategy Design Phase

Objective: Design comprehensive test coverage before writing implementation code.

CRITICAL: Testing is not an afterthought. Design tests that validate:

• Happy path scenarios
• Edge cases and error conditions
• Integration with existing functionality
• Backward compatibility if applicable

Actions:

• Identify existing test files that need updates
• Design new test files for new functionality
• Specify what each test validates
• Consider test data requirements
• Plan test execution order (unit -> integration -> e2e)

Output:

• Test files to modify (with specific test cases to add/update)
• New test files to create (with purpose of each)
• Test data or fixtures needed
• Expected test coverage metrics

Example:

Test modifications:
- `tests/test_git_commit.sh:45-67` - Update to verify milestone flag handling
  - Test case: Verify `--no-verify` used only for milestone commits
  - Test case: Verify milestone commit message format

New test files:
- `tests/test_milestone_workflow.sh` - Test complete milestone workflow
  - Test case: Create milestone commit on dev branch (should succeed)
  - Test case: Attempt milestone commit on main (should fail)
  - Test case: Verify test status included in commit message
  - Estimated complexity: ~80 lines

5. Implementation Plan Phase

Objective: Create a step-by-step implementation plan with complexity estimates.

CRITICAL: Use lines of code (LOC) to estimate complexity, NOT time durations.

Complexity guidelines:

• Trivial: 1-20 LOC (simple config changes, single function additions)
• Small: 21-50 LOC (new function with basic logic, simple test cases)
• Medium: 51-150 LOC (new feature module, moderate refactoring)
• Large: 151-400 LOC (significant feature, multiple file changes)
• Very large: 401+ LOC (major refactoring, new subsystem)

MANDATORY ORDERING: Implementation steps MUST follow this sequence:

Phase 1: Documentation (always first)

• Update interface documentation
• Add/update design documents
• Update API references
• Add usage examples

Phase 2: Test Cases (always second)

• Create new test files
• Update existing test cases
• Add test fixtures/data
• Document test scenarios

Phase 3: Implementation (always last)

• Write the actual code
• Implement the logic
• Integrate with existing code

Actions:

• NEVER put implementation before documentation or tests
• Group documentation updates into Step 1 (or Steps 1-N for large features)
• Group test case work into the next step(s)
• Only after docs and tests, begin implementation steps
• For each step, specify:
  • Exact files to change (with line ranges if known)
  • What changes to make
  • Estimated lines of code
  • Dependencies on previous steps
• Break down steps larger than 400 LOC into substeps
• Consider milestone commits for features beyond 800 LOC total

Understanding Milestone Commits:

Milestone commits are for incremental progress on large features. They allow bypassing pre-commit hooks, but this does NOT mean skipping tests:

• Tests are ALWAYS run - even for milestone commits
• Temporarily accept incomplete test passage - e.g., "35/42 tests passed"
• Track progress mile-by-mile - each milestone shows test progress
• Work toward full passage - continue until all tests pass
• Only merge when complete - all tests must pass before merging to main

Example milestone progression:

• Milestone 1: Documentation complete, tests created (0/8 tests pass)
• Milestone 2: Basic implementation (3/8 tests pass)
• Milestone 3: Edge cases handled (6/8 tests pass)
• Delivery commit: All tests pass (8/8), ready to merge

Output format:

Step N: [Brief description] (Estimated: X LOC)
- File 1: Specific change description
- File 2: Specific change description
Dependencies: [List steps that must complete first]

Example (following Design-first TDD ordering):

Step 1: Update documentation for milestone commits (Estimated: 60 LOC)
- `docs/git-msg-tags.md:15-20` - Add milestone tag definition and usage
- `claude/skills/commit-msg/SKILL.md:14-20` - Add milestone to inputs section
- `claude/skills/commit-msg/SKILL.md:40-60` - Add milestone commit section with examples
Dependencies: None

Step 2: Create test cases for milestone functionality (Estimated: 90 LOC)
- `tests/test_git_commit.sh:45-67` - Add milestone flag tests
  - Test: Verify `--no-verify` used only for milestone commits
  - Test: Verify milestone commit message format
- `tests/test_milestone_message.sh` - New test file for message validation
  - Test: Validate milestone commit on dev branch succeeds
  - Test: Validate milestone commit on main fails
Dependencies: Step 1 (documentation must be complete first)

Step 3: Implement milestone detection and handling logic (Estimated: 100 LOC)
- `claude/skills/commit-msg/SKILL.md:25-35` - Add milestone input handling
- `claude/skills/commit-msg/SKILL.md:85-88` - Add pre-commit bypass logic
Dependencies: Step 2 (tests must exist before implementation)

Total estimated complexity: 250 LOC (Medium-Large feature)
Recommended approach: Implement in single development session
Note: Follows Design-first TDD: Docs (Step 1) → Tests (Step 2) → Implementation (Step 3)

Plan Output Format

The final plan should be structured as follows:

# Implementation Plan: [Feature/Goal Name]

## Goal
[1-2 sentence problem statement]

**Success criteria:**
- [Criterion 1]
- [Criterion 2]

**Out of scope:**
- [What we're not doing]

## Codebase Analysis

**Files to modify:**
- `path/to/file1:lines` - Purpose
- `path/to/file2:lines` - Purpose

**Files to create:**
- `path/to/new/file1` - Purpose (Estimated: X LOC)
- `path/to/new/file2` - Purpose (Estimated: X LOC)

**Files to delete:**
- `path/to/deprecated/file` - Reason

**Current architecture notes:**
[Key observations about existing code]

## Interface Design

**New interfaces:**
- [Interface signatures and descriptions]

**Modified interfaces:**
- [Before/after comparisons]

**Documentation changes:**
- [Doc files to update with sections]

## Test Strategy

**Test modifications:**
- `test/file1:lines` - What to test
  - Test case: Description
  - Test case: Description

**New test files:**
- `test/new_file` - Purpose (Estimated: X LOC)
  - Test case: Description
  - Test case: Description

**Test data required:**
- [Fixtures, sample data, etc.]

## Implementation Steps

**Step 1: [Description]** (Estimated: X LOC)
- File changes
Dependencies: None

**Step 2: [Description]** (Estimated: X LOC)
- File changes
Dependencies: Step 1

...

**Total estimated complexity:** X LOC ([Complexity level])
**Recommended approach:** [Single session / Milestone commits / etc.]

Integration with Other Skills

After creating a plan, the AI agent should:

1. Present to user for approval

   • Display the complete plan
   • Ask for confirmation or revisions

2. Create GitHub issue (once approved)

   • Use the open-issue skill
   • The plan becomes the "Proposed Solution" section
   • Add appropriate [plan][tag] prefix

3. Begin implementation (after issue created)

   • Use the fork-dev-branch skill to create a development branch
   • Follow the step-by-step plan
   • Use commit-msg skill for commits (milestone commits if needed)
   • Use open-pr skill when implementation is complete

Examples

Example 1: Small Feature Addition

User request: "Add support for milestone commits in the commit-msg skill"

Plan excerpt:

# Implementation Plan: Milestone Commit Support

## Goal
Add milestone commit functionality to allow work-in-progress commits that can
bypass pre-commit hooks on development branches.

**Success criteria:**
- Milestone commits work only on development branches (not main)
- Milestone commits include test status in message
- Pre-commit hooks can be bypassed with explicit milestone flag

**Out of scope:**
- Automatic milestone detection
- Milestone progress tracking UI

## Codebase Analysis

**Files to modify:**
- `claude/skills/commit-msg/SKILL.md:14-20` - Add milestone input handling
- `claude/skills/commit-msg/SKILL.md:40-88` - Add milestone message format
- `tests/test_git_commit.sh:45-67` - Add milestone tests

**Files to create:**
- None required

**Current architecture notes:**
- Commit skill currently supports only delivery commits
- Pre-commit hook validation is mandatory for all commits
- Branch detection logic already exists in workflow

## Implementation Steps

**Step 1: Update documentation** (Estimated: 60 LOC)
- `docs/git-msg-tags.md:15-20` - Add milestone tag definition and usage rules
- `claude/skills/commit-msg/SKILL.md:14-20` - Add milestone to inputs section
- `claude/skills/commit-msg/SKILL.md:40-60` - Add milestone message format section
Dependencies: None

**Step 2: Create test cases** (Estimated: 85 LOC)
- `tests/test_git_commit.sh:45-67` - Add milestone-specific tests
  - Test: Milestone commits bypass hooks on dev branches
  - Test: Milestone commits fail on main branch
  - Test: Milestone message includes test status
- `tests/test_milestone_format.sh` - New test for message validation
Dependencies: Step 1 (documentation must define behavior first)

**Step 3: Implement milestone commit logic** (Estimated: 95 LOC)
- `claude/skills/commit-msg/SKILL.md:25-35` - Add milestone input processing
- `claude/skills/commit-msg/SKILL.md:85-88` - Add pre-commit bypass logic
Dependencies: Step 2 (tests must exist to validate implementation)

**Total estimated complexity:** 240 LOC (Medium feature)
**Recommended approach:** Single development session following Docs → Tests → Implementation

Example 2: Large Refactoring

User request: "Refactor the SDK initialization to validate directories"

Plan excerpt:

# Implementation Plan: SDK Init Directory Validation

## Goal
Add comprehensive directory validation to SDK initialization to prevent
initialization in invalid locations and provide clear error messages.

**Success criteria:**
- Validate target directory exists and is writable
- Check for conflicting files before initialization
- Provide actionable error messages
- Support both init and update modes

**Out of scope:**
- Automatic directory creation
- Backup/rollback functionality

## Codebase Analysis

**Files to modify:**
- `Makefile:45-67` - Add validation before template copying
- `docs/OPTIONS.md:25-40` - Document validation behavior

**Files to create:**
- `scripts/validate_target_dir.sh` - Directory validation logic (Est: 120 LOC)
- `tests/test_directory_validation.sh` - Validation tests (Est: 180 LOC)

## Test Strategy

**New test files:**
- `tests/test_directory_validation.sh` (Estimated: 180 LOC)
  - Test case: Valid empty directory (should pass)
  - Test case: Non-existent directory (should fail with error)
  - Test case: Directory with conflicting files (should fail with list)
  - Test case: Non-writable directory (should fail with permission error)
  - Test case: Init mode vs update mode differences

## Implementation Steps

**Step 1: Update documentation** (Estimated: 60 LOC)
- `docs/OPTIONS.md:25-40` - Document validation behavior and error messages
- `docs/OPTIONS.md:50-65` - Add examples of valid/invalid target directories
Dependencies: None

**Step 2: Create test cases** (Estimated: 180 LOC)
- `tests/test_directory_validation.sh` - New comprehensive validation test suite
  - Test: Valid empty directory initialization
  - Test: Non-existent directory rejection
  - Test: Conflicting files detection
  - Test: Permission error handling
  - Test: Init vs update mode differences
Dependencies: Step 1 (documentation defines expected behavior)

**Step 3: Implement validation script** (Estimated: 120 LOC)
- `scripts/validate_target_dir.sh` - New validation script with all checks
  - Directory existence check
  - Write permission validation
  - Conflict detection logic
  - Mode-specific validation rules
Dependencies: Step 2 (tests define all edge cases)

**Step 4: Integrate validation into Makefile** (Estimated: 60 LOC)
- `Makefile:45-67` - Add validation call before template copying
- `Makefile:70-85` - Add error handling and user feedback
Dependencies: Step 3 (validation script must exist)

**Total estimated complexity:** 420 LOC (Large feature)
**Recommended approach:** Use milestone commits for incremental progress

**Milestone strategy:**
- Milestone 1 (after Step 2): Documentation and tests complete (0/5 tests pass)
  - All tests exist but implementation not started yet
- Milestone 2 (after Step 3): Validation script implemented (3/5 tests pass)
  - Basic validation working, edge cases still failing
- Delivery commit (after Step 4): Full integration complete (5/5 tests pass)
  - All tests pass, ready for PR

**Note:** Follows Design-first TDD strictly: Docs (Step 1) → Tests (Step 2) → Implementation (Steps 3-4)
Tests are run at each milestone; failing tests are accepted temporarily as progress checkpoints.

Important Notes

1. MANDATORY ordering - Design-first TDD: Implementation steps MUST follow this order:

   • Step 1 (or Steps 1-N): Documentation updates
   • Step 2 (or Steps N+1-M): Test case creation/updates
   • Step 3+ (or Steps M+1-end): Implementation code

   NEVER put implementation before documentation or tests. This is non-negotiable.

2. No vague audit steps: The plan must contain concrete file names and line ranges, not "audit the codebase" tasks. Auditing happens during planning.

3. Quantify with LOC: Always use lines of code estimates, never time-based estimates like "2 hours" or "3 days".

4. Test-first mindset: Design tests before implementation details. Tests clarify requirements and prevent scope creep. Tests must exist before writing implementation.

5. Break down large steps: If a single step exceeds 400 LOC, break it into substeps. Consider milestone commits for features exceeding 800 LOC total.

6. Document interfaces early: Interface design comes before implementation planning. Changes to interfaces affect multiple files and should be designed carefully.

7. Use existing patterns: During audit, identify and follow existing architectural patterns and naming conventions in the codebase.

8. Be specific: Prefer "Modify file.py:45-67 to add parameter validation" over "Update the validation logic". The more specific, the better.

9. Dependencies reflect ordering: Each step's dependencies should enforce the ordering:

   • Tests depend on documentation
   • Implementation depends on tests
   • Never skip the dependency chain

10. Milestone commits run tests: When planning features that require milestone commits:

    • Tests are ALWAYS run at each milestone (not skipped)
    • Bypassing pre-commit hooks means accepting incomplete test passage temporarily
    • Each milestone must report test status (e.g., "15/20 tests passed")
    • Work incrementally until all tests pass
    • Only merge to main when all tests pass (100% passage required)