phase-5-validator
Validates Finalization Phase completion before workflow concludes. Checks documentation updates, file registry, git commits, deployment readiness, and lessons learned contributions.
When & Why to Use This Skill
The Phase 5 Validator is a comprehensive quality gate tool designed to automate the finalization of development workflows. It enforces strict standards for documentation, version control, and project hygiene, ensuring that every task is fully completed, documented, and ready for handoff or deployment. By utilizing blocking authority, it prevents workflow conclusion if critical requirements—such as single source of truth (SSOT) integrity and file size limits—are not met.
Use Cases
- Pre-deployment Quality Assurance: Automatically verify that all tests pass, documentation is current, and no temporary files exist before pushing code to production.
- Standardizing Version Control: Ensure every team member follows commit message standards and maintains a clean branch status before closing a task or merging a PR.
- Knowledge Management & Maintenance: Enforce the recording of 'lessons learned' and updates to the file registry to ensure long-term project maintainability and knowledge transfer.
- Automated Workflow Compliance: Use as a mandatory blocking gate in AI-driven coding environments to prevent agents from finishing tasks until all organizational SOPs and documentation requirements are satisfied.
| name | phase-5-validator |
|---|---|
| description | Validates Finalization Phase completion before workflow concludes. Checks documentation updates, file registry, git commits, deployment readiness, and lessons learned contributions. |
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.