agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/dry-walkthrough/SKILL.md

dry-walkthrough

Skill1 starsChanged 8 months agoMITView on GitHub

Validate an implementation plan by tracing through each change without implementing. Use when user says dry walkthrough, drywalkthrough, validate plan, or check plan. Identifies gaps, fixes the plan directly, and reports changes to terminal.

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 23 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈23

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After creating a plan, before implementation

    line 28
  2. Distinctive:

    Add backward compatibility to the plan

    line 39
  3. Distinctive:

    Write gap analysis or commentary INTO the plan file

    line 41
  4. Distinctive:

    Add a rollback plan

    line 42
  5. Distinctive:

    Add deprecation notes, stubs, code, warnings

    line 43
  6. Distinctive:

    Remove or defer goals or phases from the plan

    line 45
  7. Distinctive:

    Consider effort as a reason for choosing one approach over another

    line 47
  8. Distinctive:

    Keep the plan as clean implementation instructions only (information/background helpful to implementation is okay)

    line 50
  9. Distinctive:

    Verify assumptions against actual codebase

    line 53
  10. Distinctive:

    Remove deprecation code/notes and rollback mechanisms

    line 54
  11. Distinctive:

    Make sure the plan includes warning against using the codebase as a notepad with useless comments

    line 55
  12. Distinctive:

    Prefer the long term health of project over quick, easy, and minimal fixes

    line 56
  13. Distinctive:

    Read the plan from:

    line 62
  14. Distinctive:

    After resolving the plan path, check whether this is a part file of a multi-part plan:

    line 69
  15. Very specific:

    Detect the part suffix: If the plan filename contains _part_ (e.g., _part_a, _part_b, _part_1), this is one part of a multi-part plan.

    line 71
  16. Distinctive:

    ⚠️ SCOPE BOUNDARY — CRITICAL: If a part suffix is detected, immediately output to the terminal:

    line 73
  17. Distinctive:

    Verify the scope warning block: Check that the plan file contains the mandatory scope warning block immediately after the title line.

    line 76
  18. Distinctive:

    If the block is absent, or contains the wrong part label or wording, insert or correct it as your first edit to the plan file before …

    line 80
  19. Distinctive:

    Run a lightweight two-part scan to detect whether the plan risks reintroducing patterns that were previously fixed or conflicts with …

    line 118
  20. Distinctive:

    If this fails, skip Part B and record an informational note: "GitHub issues scan skipped — gh not authenticated."

    line 153
  21. Distinctive:

    If Part A and Part B produce no findings, record: "No historical regressions or issue overlaps detected."

    line 177
  22. Distinctive:

    Do NOT add any "gap analysis" or "issues" sections to the plan

    line 183
  23. Distinctive:

    After fixing all issues, add this exact line as the first line of the plan file:

    line 188
  24. Distinctive:

    After updating the plan, output a summary to the terminal (your response text):

    line 198

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Dry Walkthrough Skill

Validate a proposed implementation plan by performing a dry walkthrough of each change without implementing. Fix issues directly in the plan and report what changed to the terminal.

Key Principle

The plan file must remain a clean, self-contained implementation instruction set. No gap analysis, no commentary, no "issues found" sections in the plan itself. All reporting goes to terminal output.

Your role is technical validation, not strategic decision-making. Fix factual inaccuracies (wrong file paths, nonexistent functions, incorrect line numbers). Preserve all goals and scope.

When to Use

  • User says "dry walkthrough", "drywalkthrough", "dry walk", "dry run"
  • User wants to "validate plan" or "check plan"
  • User says "before implementing" and wants verification
  • After creating a plan, before implementation

Arguments

{plan_path} — Absolute path to the plan file to validate (optional: falls back to most recent temp/ artifact if omitted)

Critical Constraints

NEVER:

  • Modify any source code files
  • Implement any part of the plan
  • Add backward compatibility to the plan
  • Add fallback mechanisms
  • Write gap analysis or commentary INTO the plan file
  • Add a rollback plan
  • Add deprecation notes, stubs, code, warnings
  • Include alternative approaches that will not be part of implementation in plan
  • Remove or defer goals or phases from the plan
  • Reduce the plan's scope to a "simpler fix" - the plan defines the problem scope, not you
  • Consider effort as a reason for choosing one approach over another

ALWAYS:

  • Keep the plan as clean implementation instructions only (information/background helpful to implementation is okay)
  • Report all findings to terminal output (your response text)
  • Fix issues by directly updating the plan content
  • Verify assumptions against actual codebase
  • Remove deprecation code/notes and rollback mechanisms
  • Make sure the plan includes warning against using the codebase as a notepad with useless comments
  • Prefer the long term health of project over quick, easy, and minimal fixes

Dry Walkthrough Workflow

Step 1: Load the Plan

Read the plan from:

  • Path provided by user
  • Plan content pasted directly
  • Most recent plan in temp/ subdirectories

Multi-Part Plan Detection

After resolving the plan path, check whether this is a part file of a multi-part plan:

  1. Detect the part suffix: If the plan filename contains _part_ (e.g., _part_a, _part_b, _part_1), this is one part of a multi-part plan. Extract the part identifier (A, B, C… or number) from the suffix.
  2. ⚠️ SCOPE BOUNDARY — CRITICAL: If a part suffix is detected, immediately output to the terminal:

    "⚠️ MULTI-PART PLAN DETECTED: Validating PART {X} ONLY. This session MUST NOT read, open, reference, or validate any other part files. Sibling part files visible in temp/ or any other directory are entirely out of scope and must be ignored."

  3. Verify the scope warning block: Check that the plan file contains the mandatory scope warning block immediately after the title line. The block must match this form:
    > **PART {X} ONLY. Do not implement any other part. Other parts are separate tasks requiring explicit authorization.**
    If the block is absent, or contains the wrong part label or wording, insert or correct it as your first edit to the plan file before proceeding to phase validation.

Step 2: Extract and Validate Each Phase

For each phase, verify using subagents:

1. Do the target files exist?
2. Do the referenced functions/classes exist?
3. Are the assumptions about current state correct?
4. Will the changes introduce circular dependencies?
5. Are there hidden dependencies not mentioned?
6. Does this violate any project rules?
7. Does the implmentation make sense given the reality of the current state of code?
8. Is every new component, class, or function actually wired into the call chain? Nothing should be created but left unconnected.

Step 3: Check Cross-Phase Dependencies

Verify phase ordering:

  • Does Phase N depend on Phase N-1 completion?
  • Are there implicit dependencies not stated?
  • Could phases be reordered for safety?

Step 4: Validate Against Project Rules

PROJECT RULES CHECKLIST:
[ ] No backward compatibility code
[ ] No fallbacks that hide errors
[ ] No stakeholder sections
[ ] No PR breakdown sections
[ ] Follows existing architectural patterns
[ ] Uses existing utilities (not reinventing) unless refactoring is part of plan or provides major improvement

Step 4.5: Historical Regression Check

Run a lightweight two-part scan to detect whether the plan risks reintroducing patterns that were previously fixed or conflicts with tracked GitHub issues. This is a quick cross-reference sanity check — not a deep audit.

Defaults: Last 100 recent commits · Issues closed in last 30 days

A. Git History Scan

  1. Extract the set of source files the plan proposes to touch by grepping the plan text for file paths. Store as PLAN_FILES.
  2. Scan recent commit messages on those files for fix/revert/remove/replace keywords:
    git log --oneline -100 --format="%H %s" --grep="fix\|revert\|remove\|replace\|delete" -- {PLAN_FILES}
  3. For each matching commit, determine signal strength:
    • Strong signal: The plan proposes to add a function or class name that appears in the commit's diff as a deletion — check with: git show {hash} | grep "^-def \|^-class \|^-async def " and compare against function/class names the plan introduces.
    • Weak signal: Same file touched + fix/revert keyword in message, but no symbol-level match.
  4. Classify:
    • Strong signal → Actionable: Insert a warning note into the affected plan step: > ⚠️ Historical note: {symbol} was removed in {hash} ("{commit_message}") — verify this addition is intentional and does not reintroduce a known bug.
    • Weak signal → Informational: Record for terminal output (collected in Part C).

B. GitHub Issues Cross-Reference

  1. Check gh authentication:
    gh auth status 2>/dev/null
    If this fails, skip Part B and record an informational note: "GitHub issues scan skipped — gh not authenticated."
  2. Fetch open and recently closed issues:
    gh issue list --state open --json number,title,body --limit 100
    gh issue list --state closed --json number,title,body,closedAt --limit 100
    Filter closed issues to those closedAt within the last 30 days.
  3. Build a keyword set from the plan: target file basenames (without extension), function names mentioned in the plan, and key terms from described changes.
  4. Cross-reference each issue's title and body against the keyword set:
    • Closed issue match → Actionable: The issue specifically fixed a pattern the plan proposes to introduce. Insert a warning note into the affected plan step: > ⚠️ Historical note: Issue #{N} ("{title}") addressed this area — ensure the plan does not reintroduce the fixed pattern.
    • Open issue match → Informational: Record for terminal output: "Issue #{N}: {title} — addresses the same area. Verify alignment before implementing."

C. Collect informational findings

Gather all weak-signal git findings and open-issue area overlaps into a list. These are forwarded to Step 7 for inclusion in the ### Historical Context terminal section. If Part A and Part B produce no findings, record: "No historical regressions or issue overlaps detected."

Step 5: Fix the Plan

For each issue found:

  1. Directly edit the plan file to fix it
  2. Do NOT add any "gap analysis" or "issues" sections to the plan
  3. The plan should read as if it was correct from the start

Step 6: Mark Plan as Verified

After fixing all issues, add this exact line as the first line of the plan file:

Dry-walkthrough verified = TRUE

This marker indicates the plan has been validated and is ready for implementation. The implement-worktree skill checks for this marker before proceeding.

Step 7: Report to Terminal

After updating the plan, output a summary to the terminal (your response text):

## Dry Walkthrough Complete

**Plan:** {path}
**Status:** {PASS - Ready to implement / REVISED - See changes below}

### Changes Made
1. {What was changed and why}
2. {What was changed and why}

### Verified
- {Key assumption that was confirmed}
- {Key assumption that was confirmed}

### Historical Context
- {finding}: {description}
  (or: No historical regressions or issue overlaps detected.)

### Recommendation
{Implement as-is / Review changes before implementing}

Output Rules

ContentWhere it goes
Fixed plan contentWritten to plan file (Edit tool)
Gap analysisTerminal output (your response text)
Change summaryTerminal output (your response text)
RecommendationsTerminal output (your response text)

Example

Input: User says "dry walkthrough temp/make-plan/api_retry_plan.md"

Process:

  1. Read the plan
  2. Validate Phase 1: File exists, function exists - PASS
  3. Validate Phase 2: Found similar pattern in src/db/client.py not referenced - needs fix
  4. Validate Phase 3: Test command correct - PASS
  5. Edit the plan to add reference to existing pattern
  6. Output summary to terminal

Terminal Output:

## Dry Walkthrough Complete

**Plan:** temp/make-plan/api_retry_plan.md
**Status:** REVISED

### Changes Made
1. Phase 2: Added reference to existing retry pattern in `src/db/client.py:45-67` - implementation should follow this pattern for consistency

### Verified
- `src/api/client.py` exists with expected `__init__` signature
- No circular dependency risk identified
- Test commands are correct

### Historical Context
- Issue #302: "consolidate retry logic" — addresses the same area. Verify alignment before implementing.

### Recommendation
Ready to implement. Review the updated Phase 2 to see the pattern reference.

Plan file: Updated cleanly with no gap analysis sections - just the corrected implementation instructions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.