Skip to content
Skills Library
Management & product · Automation

plan-tracking

/plan-tracking

Guidelines for working with plan files. Claude should use this skill when the user provides a plan file (e.g., *-plan.md) to ensure task completion is tracked in the plan file itself, not just internally.

Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Guidelines for working with plan files. Claude should use this skill when the user provides a plan file (e.g., *-plan.md) to ensure task completion is tracked in the plan file itself, not just internally.

Original author description

Guidelines for working with plan files. Claude should use this skill when the user provides a plan file (e.g., *-plan.md) to ensure task completion is tracked in the plan file itself, not just internally.

How it works

  1. Core Rule
  2. ⚠️ Verifying Observable and Evidence (CRITICAL - READ THIS)
  3. Migration Planning
  4. Review Plans for Technical Correctness
  5. Workflow
  6. Continue Without Stopping
  7. Why This Matters
  8. Common Mistake
  9. When to Apply
  10. Commit Guidelines
Original SKILL.md headings · 148 lines, 788 words
SKILL.md preview
---
name: plan-tracking
description: Guidelines for working with plan files. Claude should use this skill when the user provides a plan file (e.g., *-plan.md) to ensure task completion is tracked in the plan file itself, not just internally.
---

# Plan File Tracking Guidelines

When working from a plan file (markdown file with task checkboxes), follow these guidelines to ensure proper tracking.

## Core Rule

**The plan file is the source of truth for task completion status.**

Use the `plan-file-management` skill's subcommands to read and update plan files:
- **Find next task**: `plan-file-management` → `get-next-task`
- **Mark task complete**: `plan-file-management` → `mark-task-complete`

See the `plan-file-management` skill for invocation details.

Do NOT rely on internal tracking (like TodoWrite) as a substitute for updating the actual plan file.

## ⚠️ Verifying Observable and Evidence (CRITICAL - READ THIS)

**THIS IS THE MOST IMPORTANT SECTION OF THIS SKILL.**

**A task is NOT complete until the Observable outcome is actually observed and the Evidence is actually collected.**

If a task has these fields:
- **Observable**: What should be true after the task is complete
- **Evidence**: How to verify the observable

Then **tests** must verify the Evidence - not the agent manually running commands and checking output.

This applies to all test types:
- JUnit/unit tests
- Integration tests
- Component tests
- Shell test scripts

Example task:
```
- [ ] **Task 1.3: POST /orders endpoint creates order and returns 201**
  - Observable: Endpoint accepts order JSON, persists to database, returns 201 with order ID
  - Evidence: Integration test POSTs valid order, asserts 201 response, asserts order exists in database
```

The test must contain assertions that verify the Evidence:
```java
@Test
void createOrder_returnsCreatedWithOrderId() {
    var response = restTemplate.postForEntity("/orders", validOrderRequest, OrderResponse.class);

    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
    assertThat(response.getBody().getId()).isNotNull();

    // Verify persisted to database
    var saved = orderRepository.findById(response.getBody().getId());
    assertThat(saved).isPresent();
    assertThat(saved.get().getCustomerId()).isEqualTo(validOrderRequest.getCustomerId());
}
```

WRONG: Agent writes the endpoint code, assumes it works because the code looks right
RIGHT: Tests contain assertions for the Evidence criteria; tests pass = Evidence verified

**Tests are the source of truth for verification, not the agent's judgment.**

## Migration Planning

When creating migration or upgrade plans for existing codebases:
1. Before describing any file/directory creation tasks, verify whether the target already exists using Glob or Read
2. Use precise language: "Transform" or "Convert" for existing items, "Create" only for genuinely new items
3. Include a "Current State" section in plans that documents what exists before transformation

## Review Plans for Technical Correctness

Before implementing a task from the plan, review its implementation details for technical flaws:

- Apply fundamental engineering principles (e.g., uniqueness constraints belong at database level, not application level)
- If the plan specifies a flawed approach, fix it before proceeding
- Do not blindly follow implementation details that violate best practices

## Workflow

For each task in the plan:

1. Get the next task using `plan-file-management` → `get-next-task`
2. **Review for technical correctness** before implementing
3. Implement the task (write test, implement code, verify)
4. **Verify Observable and Evidence criteria** - tests must pass that verify the Evidence (see critical section above)
5. **Mark task complete* using `plan-file-management` → `mark-task-complete`
6. Continue to the next task

## Continue Without Stopping

When implementing a documented plan:
- Continue through all phases without stopping for confirmation
- Only pause if blocked, uncertain about requirements, or encountering errors
- The plan itself serves as the user's approval to proceed
- Summarize progress periodically but don't ask "should I continue?"

## Why This Matters

- The plan file is visible to the user and persists across sessions
- Internal tracking (TodoWrite) is ephemeral and not visible in the codebase
- Commits should include both the implementation AND the updated plan
- Other developers can see progress by looking at the plan file

## Common Mistake

BAD:
```
Complete task 1.1
Update internal TodoWrite
Complete task 1.2
Update internal TodoWrite
... (plan file never updated)
```

GOOD:
```
Complete task 1.1
Use plan-file-management → mark-task-complete for thread 1, task 1
Complete task 1.2
Use plan-file-management → mark-task-complete for thread 1, task 2
```

## When to Apply

Apply this guideline when:
- User provides a plan file path (e.g., `*-plan.md`, `*-tasks.md`)
- User says "follow the plan" or "implement from the plan"
- Working with any markdown file containing `- [ ]` task checkboxes

## Commit Guidelines

When committing completed tasks:
1. Stage the implementation changes
2. Stage the updated plan file (with checkbox marked)
3. Commit together so the commit reflects both the work done and the progress tracked

## Commit Verification for Plan Files

Before running `git commit`, always:
1. Run `git status` from the **repository root** (not a subdirectory)
2. Verify the plan file appears in "Changes to be committed"
3. If the plan file is not staged, explicitly add it: `git add path/to/plan.md`

When committing from a subdirectory:
- Use absolute paths or navigate to repo root first
- Example: `git add /path/to/plan.md` or `cd /repo/root && git add .`

Versions

The database has no other skills named plan-tracking.

Database snapshot: 13.11.2026 · package version 15d9dabd1c7c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100plan-only
    Plan-only mode that replicates Claude Code's built-in plan mode workflow but stops after the user approves the plan — no auto-execution. Use when the user wants to plan without executing, says "plan only", "just plan", "plan but don't execute", or when another skill needs…
  • 84review-tasks
    Reviews an implementation task plan against its approved proposal, specifications, design, and test plan, finding only defects that can be corrected in the task files; use when asked to review tasks, review an implementation plan, verify task and automated-test coverage, or…
  • 100plan-it
    Produces an implementation plan and hands off to /plan-review. TRIGGER when: asked for a plan or implementation strategy for work spanning multiple files or domains. DO NOT TRIGGER when: single-file tweaks, "just implement it" requests, or when a plan already exists (use /plan-review instead).
  • 100planprocess
    Use when the user asks to "execute the plan", "run the plan", "/ar:planprocess", or "/ar:pp". Executes an approved plan step by step with the wait process, task tracking, and verification before each completion claim.
  • 100run-plan
    Execute a written plan. Use when handed a plan file, or resuming one mid-flight. Not for writing the plan (write-plan) or reviewing a suspect one (plan-hunt).
  • 90finalize-plan
    Review a plan for completeness before accepting it. Use when in plan mode, before approving the plan and clearing context, to confirm that key decisions, file names, commands, and constraints from the conversation are captured in the plan file so a fresh context can execute it.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.