Phase 5 (Finalization) Validation Skill

Purpose: Automate validation that all work is properly documented, committed, and ready for deployment/handoff.

When to Use: Final validation before marking workflow complete.

How to Use This Skill

Executable Script: execute.sh

# Basic usage (no parameters required)
bash .claude/skills/phase-5-validator/execute.sh

# Show help
bash .claude/skills/phase-5-validator/execute.sh --help

Parameters:

No parameters required - validates current project state

Script validates:

🚨 BLOCKING: Single source of truth (no bash duplication in skills)
🚨 BLOCKING: Lessons learned file sizes (max 2,000 lines)
Git & version control (commits, messages, branch status, conflicts)
Documentation (file registry, PROGRESS.md, feature docs, CLAUDE.md)
Lessons learned (new entries, format, cross-references)
Deployment readiness (tests passing, no blocking issues, deployment notes)
Cleanup (temp files, session work, orphaned files)

Exit codes:

0: Finalization complete, workflow can conclude
1: BLOCKING violations OR quality gates not met

CRITICAL: This validator has BLOCKING AUTHORITY and can prevent workflow completion.

Quality Gate Checklist

🚨 Single Source of Truth (BLOCKING - Not Scored)

[ ] ALL skills validated for duplication (MANDATORY)
[ ] No bash command duplication in agent definitions
[ ] No procedural duplication in lessons learned
[ ] No automation duplication in process docs
[ ] Skills properly referenced (not duplicated)

CRITICAL: This check runs FIRST with BLOCKING AUTHORITY. Any violations = immediate failure before scoring begins.

🚨 Lessons File Sizes (BLOCKING - Not Scored)

[ ] ALL lessons files checked for size (MANDATORY)
[ ] No files exceeding 1700 line maximum
[ ] Files approaching 90% threshold identified
[ ] Multi-file structure properly maintained
[ ] Size violations provide split instructions

CRITICAL: This check runs SECOND with BLOCKING AUTHORITY. Files exceeding 1700 lines = immediate failure before scoring begins.

Git & Version Control (25 points)

[ ] All changes committed (10 points)
[ ] Commit messages follow standards (5 points)
[ ] Branch is up to date (5 points)
[ ] No merge conflicts (5 points)

Documentation (30 points)

[ ] File registry updated (10 points)
[ ] PROGRESS.md updated (5 points)
[ ] Feature documentation complete (10 points)
[ ] CLAUDE.md updated if needed (5 points)

Lessons Learned (20 points)

[ ] New lessons documented (10 points)
[ ] Lessons follow format (5 points)
[ ] Cross-references added (5 points)

Deployment Readiness (15 points)

[ ] All tests passing (5 points)
[ ] No blocking issues (5 points)
[ ] Deployment notes present (5 points)

Cleanup (10 points)

[ ] Temporary files removed (3 points)
[ ] Session work archived (3 points)
[ ] Orphaned files resolved (4 points)

Usage Examples

From Orchestrator

Use the phase-5-validator skill to check if work is ready to finalize

Manual Validation

# Run finalization validation
bash .claude/skills/phase-5-validator.md

Common Issues

Issue: File Registry Not Updated

CRITICAL: Every file operation must be logged.

Solution:

# Update file registry
echo "| $(date +%Y-%m-%d) | /path/to/file | CREATED | Purpose | Task | ACTIVE | - |" >> docs/architecture/file-registry.md

Issue: Uncommitted Changes

Solution:

# Check status
git status

# Commit changes
git add .
git commit -m "feat: implement user management feature

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Issue: Missing Documentation

Required documents:

business-requirements.md
functional-spec.md
database-design.md
ui-ux-design.md
implementation-notes.md
deployment-notes.md

Issue: Temporary Files

Solution:

# Find and remove
find . -name "*.tmp" -delete
find . -name "*.bak" -delete

# Or move to session-work
mkdir -p session-work/$(date +%Y-%m-%d)
mv status.md session-work/$(date +%Y-%m-%d)/

Mandatory Finalization Checklist

Before marking workflow complete:

🚨 Single Source of Truth (BLOCKING - FIRST CHECK)
- [ ] ALL skills validated for duplication (MANDATORY)
- [ ] No bash commands duplicated in agent definitions
- [ ] No procedures duplicated in lessons learned
- [ ] No automation duplicated in process docs
- [ ] Skills properly referenced from other docs
- ANY VIOLATIONS = IMMEDIATE WORKFLOW FAILURE
Git
- [ ] All changes committed
- [ ] Commit messages follow standards
- [ ] Branch clean (no conflicts)
Documentation
- [ ] File registry current
- [ ] Feature docs complete
- [ ] PROGRESS.md updated
- [ ] Deployment notes written
Lessons Learned
- [ ] New patterns documented
- [ ] Problems and solutions recorded
- [ ] Cross-references added
Quality
- [ ] All tests passing (100%)
- [ ] No blocking issues
- [ ] Code reviewed
Cleanup
- [ ] Temporary files removed
- [ ] Session work organized
- [ ] No orphaned files

Output Format

{
  "phase": "finalization",
  "status": "pass|fail",
  "singleSourceOfTruth": {
    "validated": true,
    "skillsChecked": 13,
    "violations": 0,
    "blocking": false,
    "note": "CRITICAL: This check runs FIRST. Any violations = immediate failure."
  },
  "score": 87,
  "maxScore": 100,
  "percentage": 87,
  "requiredPercentage": 80,
  "git": {
    "uncommittedChanges": 0,
    "commitMessage": "standards-compliant",
    "upToDate": true,
    "conflicts": false
  },
  "documentation": {
    "fileRegistry": "updated",
    "progress": "updated",
    "featureDocs": "complete",
    "claude": "not-needed"
  },
  "lessonsLearned": {
    "newLessons": 2,
    "formatCompliant": true,
    "crossReferences": true
  },
  "deployment": {
    "testsPass": true,
    "blockingIssues": 0,
    "notesPresent": true
  },
  "cleanup": {
    "tempFiles": 0,
    "sessionWork": "organized",
    "orphanedFiles": 0
  },
  "readyToFinalize": true,
  "nextSteps": [
    "Deploy to staging (if approved)",
    "Close workflow",
    "Update project status"
  ]
}

Integration with Quality Gates

Quality gate thresholds by work type:

Feature: 80% required
Bug Fix: 75% required
Hotfix: 70% required
Documentation: 90% required
Refactoring: 85% required

Progressive Disclosure

Initial Context: Show quick status check (committed, documented, tested) On Request: Show full scoring breakdown On Failure: Show specific missing items with actionable fixes On Pass: Show next steps and finalization instructions

Remember: Finalization is about ensuring nothing is forgotten. Documentation, commits, and lessons learned ensure the work is sustainable and maintainable long-term.