validate-plan

Validate Plan

!accelerator config context --skill validate-plan --fail-safe !accelerator config agents --fail-safe

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.

Plans directory: !accelerator config path plans --fail-safe Validations directory: !accelerator config path validations --fail-safe

Plan Validation Template

The template below defines the frontmatter and body structure that every plan validation report must carry. Read it now — use it to guide what information you record in the validation process and what shape you persist in Step 4.

!accelerator config template validation --fail-safe

You are tasked with validating that an implementation plan was correctly executed, verifying all success criteria and identifying any deviations or issues.

Initial Setup

When invoked:

1. Determine context - Are you in an existing conversation or starting fresh?

• If existing: Review what was implemented in this session
• If fresh: Need to discover what was done through the session's VCS and codebase analysis

2. Locate the plan:

• If plan path provided, use it
• Otherwise, search recent commits for plan references or ask user

3. Gather implementation evidence:

If the SessionStart VCS Command Reference is not in context — validate-plan often runs late in a long session, after it may have been compacted out — re-derive it first with accelerator vcs detect --descriptive and read the idioms out of the emitted additionalContext string.

• Recent commits: list the checkout's recent revisions using the session's VCS log command (see the SessionStart VCS Command Reference).
• Implementation diff: take the cumulative change since the trunk divergence point using the session's VCS diff-range idiom (see the SessionStart VCS Command Reference).
• Run the repository's checks from its root, aborting if the root cannot be resolved (out of a repository, accelerator vcs root exits non-zero, so the assignment fails and the && chain stops rather than running make in the wrong tree):

  root="$(accelerator vcs root)" && cd "$root" && make check test
  

Validation Process

Step 1: Context Discovery

If starting fresh or need more context:

1. Read the implementation plan completely
2. Identify what should have changed:

• List all files that should be modified
• Note all success criteria (automated and manual)
• Identify key functionality to verify

3. Spawn parallel research tasks to discover implementation:

   Task 1 - Verify database changes:
   Research if migration [N] was added and schema changes match plan.
   Check: migration files, schema version, table structure
   Return: What was implemented vs what plan specified
   
   Task 2 - Verify code changes:
   Find all modified files related to [feature].
   Compare actual changes to plan specifications.
   Return: File-by-file comparison of planned vs actual
   
   Task 3 - Verify test coverage:
   Check if tests were added/modified as specified.
   Run test commands and capture results.
   Return: Test status and any missing coverage
   

Step 2: Systematic Validation

For each phase in the plan:

1. Check completion status:

• Look for checkmarks in the plan (- [x])
• Verify the actual code matches claimed completion

2. Run automated verification:

• Execute each command from "Automated Verification"
• Document pass/fail status
• If failures, investigate root cause

3. Assess manual criteria:

• List what needs manual testing
• Provide clear steps for user verification

4. Think deeply about edge cases:

• Were error conditions handled?
• Are there missing validations?
• Could the implementation break existing functionality?

Step 3: Generate Validation Report

Compose the validation report body following the structure defined in the Plan Validation Template at the top of this skill (Implementation Status, Automated Verification Results, Code Review Findings, Manual Testing Required, Recommendations).

Step 4: Persist the Validation Report

Write the validation report to the configured validations directory:

1. Derive the filename from the plan filename: extract the filename stem (without directory path or .md extension) regardless of how the path was provided. For example, if the plan is {plans directory}/2026-03-22-improve-error-handling.md, the validation is {validations directory}/2026-03-22-improve-error-handling-validation.md.

2. Create the configured validations directory if it doesn't exist.

Populate frontmatter

The target: field is filled automatically from the plan reference under validation — this is what makes the report traceable back to the plan it covers. Per ADR-0034, the typed-linkage form is "plan:<plan-id>".

Before writing the validation file, capture metadata and substitute the unified base fields and per-type extras into the template's frontmatter block:

1. Invoke accelerator corpus metadata derive to obtain Current Date/Time (UTC):.
2. Substitute every field below with the indicated value:
   • type: ← plan-validation
   • id: ← the validation filename stem (e.g. 2026-05-30-0065-update-artifact-templates-to-unified-schema-validation), always quoted as a YAML string
   • title: ← Validation Report: {plan title}
   • date: ← the Current Date/Time (UTC): value
   • author: ← the author value resolved per create-work-item/SKILL.md:578-580
   • producer: ← validate-plan
   • status: ← complete
   • last_updated: ← the same Current Date/Time (UTC): value
   • last_updated_by: ← the same value resolved for author
   • schema_version: ← 1 (bare integer, not quoted)
   • parent: ← typed-linkage ref to the parent plan ("plan:NNNN"). Fill when the validation names a parent plan; otherwise omit the key.
   • target: ← "plan:<plan-id>" (e.g. "plan:2026-05-30-0065-update-artifact-templates-to-unified-schema"); the typed-linkage ref to the plan being validated, per ADR-0034. Always fill — every validation has a target.
   • relates_to: ← list of typed-linkage refs to related artifacts (["plan-validation:NNNN", ...]). Fill when related validations are explicit; otherwise omit the key.
   • result: ← pass | partial | fail per the Implementation Status of the report (see derivation rule below)
3. Write the file with the substituted frontmatter block followed by the validation report body from Step 3.

Determine the result field from the report:

• pass: all phases fully implemented, all automated checks pass
• partial: some phases implemented or some checks failing
• fail: major deviations or critical failures

4. If the validation result is pass, update the plan's frontmatter status field to done (if the plan has YAML frontmatter with a status field). This closes the plan lifecycle.

5. Inform the user where the report was saved:

Validation report saved to {validations directory}/{filename}.md

Validate the frontmatter: after writing, run corpus frontmatter validate over the validation report you just wrote:

accelerator corpus frontmatter validate --file <path>

If it exits non-zero, the report violates the canonical frontmatter standard; report the emitted violation and fix the frontmatter before completing.

Working with Existing Context

If you were part of the implementation:

• Review the conversation history
• Check your todo list for what was completed
• Focus validation on work done in this session
• Be honest about any shortcuts or incomplete items

Important Guidelines

1. Be thorough but practical - Focus on what matters
2. Run all automated checks - Don't skip verification commands
3. Document everything - Both successes and issues
4. Think critically - Question if the implementation truly solves the problem
5. Consider maintenance - Will this be maintainable long-term?

Validation Checklist

Always verify:

• [ ] All phases marked complete are actually done
• [ ] Automated tests pass
• [ ] Code follows existing patterns
• [ ] No regressions introduced
• [ ] Error handling is robust
• [ ] Documentation updated if needed
• [ ] Manual test steps are clear

Relationship to Other Commands

Recommended workflow:

1. /implement-plan - Execute the implementation
2. /commit - Create atomic commits for changes
3. /validate-plan - Verify implementation correctness (saves report to the configured validations directory)
4. /describe-pr - Generate PR description

The validation works best after commits are made, as it can analyze the VCS history to understand what was implemented.

Remember: Good validation catches issues before they reach production. Be constructive but thorough in identifying gaps or improvements.

!accelerator config instructions validate-plan --fail-safe