When to Use This Skill
✅ Use when:
- Monitoring health of operational submodules
- Generating status reports for all 41+ submodules
- Tracking git synchronization across ecosystem
- Identifying outdated or broken submodules
- Creating health dashboards and metrics
❌ Don't use when:
- Initial submodule setup (use
submodule-setup) - Post-setup verification (use
submodule-validation) - Making configuration changes (use
submodule-configuration) - Debugging specific issues (use targeted troubleshooting)
Core Capabilities
1. Git Status Monitoring
Tracks git status across all submodules:
- Uncommitted changes detection
- Unpushed commits identification
- Branch synchronization with remote
- Detached HEAD warnings
- Merge conflict detection
- Stale branches identification
2. Symlink Health Checks
Verifies symlink integrity across ecosystem:
- Broken symlink detection
- Symlink accessibility validation
- Framework connectivity verification
- Performance impact assessment
- Automatic repair suggestions
3. Update Tracking
Monitors submodule update status:
- Parent repository submodule references
- Local vs remote version comparison
- Pending updates identification
- Update history tracking
- Dependency version tracking
4. Dashboard Generation
Creates comprehensive health dashboards:
- Ecosystem-wide status overview
- Per-category health summaries
- Individual submodule health cards
- Trend analysis and metrics
- Alert and warning aggregation
Usage Pattern
Step 1: Run Health Check
Execute health check across all or specific submodules:
# All submodules
## How to Use This Skill
1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill
.coditect/scripts/submodule-health-check.py --all
# Specific category
.coditect/scripts/submodule-health-check.py --category cloud
# Single submodule
.coditect/scripts/submodule-health-check.py --path submodules/cloud/coditect-cloud-backend
Step 2: Review Health Report
Analyze the generated health report:
- ✅ Healthy - No issues detected
- ⚠️ Warning - Minor issues or recommendations
- ❌ Critical - Major issues requiring attention
- 📊 Metrics - Health scores and trends
Step 3: Investigate Issues
For any warnings or critical issues, investigate:
# Check specific submodule
cd submodules/cloud/problematic-service
# Check git status
git status
git log -5
# Check symlinks
ls -la .coditect
ls .coditect/agents/ | wc -l
# Check remote sync
git fetch
git status
Step 4: Fix Issues
Apply fixes for detected issues:
- Commit uncommitted changes
- Push unpushed commits
- Fix broken symlinks
- Update submodule references
- Resolve conflicts
Step 5: Verify Fixes
Re-run health check to confirm fixes:
.coditect/scripts/submodule-health-check.py --path submodules/cloud/fixed-service
Health Check Categories
Git Health
- Uncommitted Changes: Files modified but not committed
- Unpushed Commits: Commits not pushed to remote
- Branch Sync: Local branch behind/ahead of remote
- Detached HEAD: Not on a branch
- Conflicts: Merge conflicts present
Symlink Health
- Broken Links: Symlinks pointing to non-existent targets
- Inaccessible: Symlinks exist but target not readable
- Missing Links: Required symlinks not present
- Performance: Symlink resolution time
Update Health
- Outdated: Submodule reference older than remote
- Diverged: Local and remote have diverged
- Stale: No updates in extended period
- Version Mismatch: Dependency versions inconsistent
Operational Health
- Build Status: CI/CD build passing/failing
- Test Coverage: Test coverage percentage
- Documentation: Documentation up to date
- Activity: Recent commit activity
Health Scoring
100-90: Excellent
- All checks passing
- No warnings
- Recent activity
- Up to date
89-70: Good
- Minor warnings
- Generally healthy
- Some maintenance needed
- Acceptable state
69-50: Fair
- Multiple warnings
- Attention recommended
- Maintenance overdue
- Requires action soon
49-0: Poor
- Critical issues
- Immediate action required
- Multiple failures
- Broken state
Dashboard Format
CODITECT Submodule Health Dashboard
Generated: 2025-11-21 10:30:00
=== Overview ===
Total Submodules: 41
Healthy: 35 (85%)
Warnings: 4 (10%)
Critical: 2 (5%)
Average Health Score: 87/100
=== Category Summary ===
cloud (4 submodules): 92/100 ✅
dev (9 submodules): 88/100 ✅
gtm (6 submodules): 75/100 ⚠️
labs (11 submodules): 82/100 ✅
docs (5 submodules): 90/100 ✅
ops (3 submodules): 85/100 ✅
market (2 submodules): 65/100 ⚠️
core (3 submodules): 95/100 ✅
=== Critical Issues ===
1. submodules/market/coditect-market-agents
- ❌ 15 uncommitted changes
- ❌ Broken .coditect symlink
- Score: 45/100
2. submodules/gtm/coditect-gtm-crm
- ❌ 3 unpushed commits
- ⚠️ 5 days behind remote
- Score: 48/100
=== Recommendations ===
1. Fix broken symlinks in 2 submodules
2. Commit and push pending changes in 4 submodules
3. Update 3 submodules to latest remote
4. Review stale branches in 2 submodules
Examples
See examples/ directory for:
quick-health-check.sh- Fast health checkdetailed-health-report.py- Comprehensive reporthealth-dashboard.sh- Generate dashboardfix-common-issues.sh- Auto-fix common problems
Templates
See templates/ directory for:
health-report.md- Standard report formatdashboard.html- HTML dashboard templatealerts.json- Alert configuration
Monitoring Schedule
Daily:
- Quick health check across all submodules
- Email summary of critical issues
Weekly:
- Comprehensive health report
- Trend analysis
- Dashboard update
Monthly:
- Full ecosystem audit
- Performance metrics
- Optimization recommendations
Integration Points
Works with:
submodule-validationskill - Validation checks- CI/CD systems - Build and test status
- Monitoring tools - Metrics and alerts
Used by:
submodule-orchestratoragent - Health monitoring- DevOps dashboards - Status visualization
Automation
Scheduled Health Checks
# Add to crontab for daily checks
0 9 * * * cd /path/to/rollout-master && .coditect/scripts/submodule-health-check.py --all --email
CI/CD Integration
# GitHub Actions workflow
name: Submodule Health Check
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight
jobs:
health-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: .coditect/scripts/submodule-health-check.py --all --ci
Related Skills
- submodule-validation - Post-setup verification
- submodule-configuration - Configuration management
- submodule-setup - Initial setup
Related Agents
- submodule-orchestrator - Coordinates health monitoring
Multi-Context Window Support
This skill supports long-running health monitoring tasks across multiple context windows using Claude 4.5's enhanced state management capabilities.
State Tracking
Checkpoint State (JSON):
{
"health_check_id": "health_20251129_150000",
"scan_scope": "all_submodules",
"phase": "git_status_complete",
"submodules_scanned": 25,
"total_submodules": 41,
"health_scores": {
"excellent": 18,
"good": 5,
"fair": 1,
"poor": 1
},
"critical_issues": [
{"submodule": "submodules/market/agents", "issue": "15 uncommitted changes"}
],
"warnings": [
{"submodule": "submodules/gtm/crm", "issue": "3 unpushed commits"}
],
"token_usage": 15000,
"created_at": "2025-11-29T15:00:00Z"
}
Progress Notes (Markdown):
# Submodule Health Check Progress - 2025-11-29
## Completed
- Scanned 25/41 submodules
- Git status: 20 clean, 3 uncommitted, 2 unpushed
- Symlink health: 23 healthy, 2 warnings
- Categories completed: cloud (4/4), dev (9/9), gtm (6/6), labs (6/11)
## In Progress
- Labs category (6/11 complete)
- Update tracking pending for all categories
## Critical Issues Found
1. submodules/market/agents - 15 uncommitted changes + broken symlink
## Next Actions
- Complete labs category health checks
- Scan market, docs, ops, core categories
- Generate comprehensive dashboard
Session Recovery
When starting a fresh context window after health monitoring work:
- Load Checkpoint State: Read
.coditect/checkpoints/submodule-health-latest.json - Review Progress Notes: Check
submodule-health-progress.mdfor scan status - Resume Scanning: Continue from last completed category
- Aggregate Results: Combine previous checkpoint data with new scans
- Generate Dashboard: Create comprehensive health report
Recovery Commands:
# 1. Check latest checkpoint
cat .coditect/checkpoints/submodule-health-latest.json | jq '.health_scores'
# 2. Review progress
tail -30 submodule-health-progress.md
# 3. See which categories completed
cat .coditect/checkpoints/submodule-health-latest.json | jq '.categories_completed'
# 4. Quick status of pending submodules
git submodule status | grep -E "(market|docs|ops|core)"
State Management Best Practices
Checkpoint Files (JSON Schema):
- Store in
.coditect/checkpoints/submodule-health-{timestamp}.json - Track scan progress (submodules scanned vs total)
- Record health scores by category and overall
- Include critical issues and warnings for immediate attention
Progress Tracking (Markdown Narrative):
- Maintain
submodule-health-progress.mdwith scan results - Document issues found with severity levels
- Track fixes applied during monitoring
- List recommendations for follow-up actions
Git Integration:
- Save health dashboard to
.coditect/reports/health-dashboard-{date}.md - Create issues for critical findings (GitHub integration)
- Tag reports:
git tag health-check-{date}
Progress Checkpoints
Natural Breaking Points:
- After each category completed (cloud, dev, gtm, labs, etc.)
- After git status scan complete
- After symlink health check complete
- After update tracking complete
- After dashboard generation
Checkpoint Creation Pattern:
# Automatic checkpoint creation after each category
if category_complete or submodules_scanned % 10 == 0:
create_checkpoint({
"scan_scope": scope,
"submodules_scanned": count,
"health_scores": score_breakdown,
"critical_issues": issues_list,
"tokens": current_token_usage
})
Example: Multi-Context Ecosystem Health Scan
Context Window 1: First 20 Submodules
{
"checkpoint_id": "ckpt_health_scan_part1",
"phase": "partial_scan",
"categories_completed": ["cloud", "dev", "gtm"],
"submodules_scanned": 19,
"average_health_score": 87,
"critical_issues": 1,
"warnings": 3,
"next_action": "Continue with labs, market, docs categories",
"token_usage": 18000
}
Context Window 2: Remaining Submodules + Dashboard
# Resume from checkpoint
cat .coditect/checkpoints/ckpt_health_scan_part1.json
# Continue scanning remaining categories
# (Context restored in 3 minutes vs 20 minutes from scratch)
{
"checkpoint_id": "ckpt_health_scan_complete",
"phase": "dashboard_generated",
"total_submodules": 41,
"overall_health_score": 85,
"dashboard_path": ".coditect/reports/health-dashboard-2025-11-29.md",
"token_usage": 14000
}
Token Savings: 18000 (first context) + 14000 (second context) = 32000 total vs. 55000 without checkpoint = 42% reduction
Reference: See docs/CLAUDE-4.5-BEST-PRACTICES.md for complete multi-context window workflow guidance.
Success Output
When this skill completes successfully, output:
✅ SKILL COMPLETE: submodule-health
Completed:
- [x] Health check executed across all submodules
- [x] Git status monitored (XX/YY clean)
- [x] Symlink health verified (XX/YY healthy)
- [x] Update tracking completed
- [x] Dashboard generated
Outputs:
- .coditect/reports/health-dashboard-[date].md
- .coditect/checkpoints/submodule-health-latest.json
- submodule-health-progress.md
Health Summary:
- Total Submodules: XX
- Healthy: XX (XX%)
- Warnings: XX (XX%)
- Critical: XX (XX%)
- Average Health Score: XX/100
Critical Issues: XX requiring immediate attention
Completion Checklist
Before marking this skill as complete, verify:
- All submodules scanned (total count matches expected)
- Git status checked for uncommitted changes and unpushed commits
- Symlink health validated (.coditect links verified)
- Update tracking completed (local vs remote comparison)
- Health dashboard generated with all sections
- Critical issues documented with severity levels
- Checkpoint created with scan results
- Recommendations provided for each issue category
Failure Indicators
This skill has FAILED if:
- ❌ Submodule count mismatch (scanned ≠ expected total)
- ❌ Git status check errors (inaccessible repositories)
- ❌ Broken symlinks not detected (false negatives)
- ❌ Dashboard generation incomplete (missing sections)
- ❌ Health scores not calculated (missing metrics)
- ❌ Critical issues not categorized by severity
- ❌ No actionable recommendations provided
- ❌ Checkpoint creation failed (state not saved)
When NOT to Use
Do NOT use this skill when:
- Initial submodule setup - Use
submodule-setupskill instead - Post-setup verification - Use
submodule-validationskill for first-time checks - Making configuration changes - Use
submodule-configurationskill - Debugging specific issues - Use targeted troubleshooting for known problems
- Single submodule focus - Just check that one submodule directly with git commands
- Pre-commit checks - Use git pre-commit hooks, not full ecosystem scan
- Continuous monitoring - Use automated CI/CD health checks instead
Use these alternatives instead:
- Initial setup:
submodule-setupskill - Post-setup validation:
submodule-validationskill - Configuration:
submodule-configurationskill - Specific debugging:
git status,git log, symlink verification commands - Single submodule: Direct git commands in that submodule
- CI/CD: GitHub Actions or GitLab CI health check jobs
Anti-Patterns (Avoid)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Scanning without inventory | Incomplete coverage, missed submodules | Always start with complete submodule list inventory |
| Ignoring warnings | Small issues become critical over time | Address warnings promptly before they escalate |
| No categorization | All issues treated equally, wrong priorities | Categorize by severity (critical/high/medium/low) |
| Skipping symlink checks | Framework connectivity breaks silently | Validate all .coditect symlinks every scan |
| Manual fixes without re-scan | Fixes not verified, issues persist | Always re-run health check after fixes |
| No checkpoint creation | Progress lost across context windows | Create checkpoints after each category completed |
| Dashboard without recommendations | Identifies problems but no solutions | Always provide actionable next steps |
| Incomplete git status | Misses unpushed commits or conflicts | Check uncommitted, unpushed, branch sync, detached HEAD |
| Ignoring update tracking | Submodules fall behind remote | Compare local vs remote for all submodules |
| No trend analysis | Can't see if health improving/degrading | Track health scores over time in reports |
Principles
This skill embodies these CODITECT principles:
#1 Recycle → Extend → Re-Use → Create
- Reuse health check scripts across monitoring cycles
- Extend with category-specific health metrics as needed
- Create reusable dashboard templates
#2 First Principles Thinking
- Understand WHY submodule health matters (framework integrity, sync, collaboration)
- Question what "healthy" means for different submodule types
- Design checks that measure actual operational health
#3 Keep It Simple
- Start with essential checks: git status, symlinks, updates
- Add complexity only when baseline health established
- Clear severity levels: critical vs warning vs info
#5 Eliminate Ambiguity
- Explicit health scores (0-100) with grade boundaries
- Clear categorization of issues by type and severity
- Unambiguous recommendations for each issue
#6 Clear, Understandable, Explainable
- Dashboard visualizes health at ecosystem, category, and submodule levels
- Issues documented with context and impact
- Recommendations explain what to do and why
#8 No Assumptions
- Don't assume clean git status; verify uncommitted changes
- Don't assume symlinks work; test accessibility
- Don't assume up-to-date; check remote comparison
#11 Automate Everything
- Automated scanning across all submodules
- Automated health scoring and categorization
- Automated dashboard generation and alerting
Full Standard: CODITECT-STANDARD-AUTOMATION.md
Version: 1.1.0 | Updated: 2026-01-04 | Quality Standard: SKILL-QUALITY-STANDARD.md v1.0.0