Component QA Remediation Plan
Generated: 2026-02-07 | Source: ADR-161 QA Grading Framework | Total: 2,122 components
Executive Summary
| Type | Count | Avg Score | Grade | Target | Gap | Priority |
|---|
| Agents | 766 | 91.4% | A | 80% | +11.4 | Maintenance |
| Hooks | 109 | 84.0% | B | 80% | +4.0 | Maintenance |
| Scripts | 433 | 72.9% | C | 80% | -7.1 | Medium |
| Commands | 363 | 69.5% | D | 80% | -10.5 | High |
| Workflows | 7 | 65.1% | D | 80% | -14.9 | High |
| Skills | 430 | 61.2% | D | 80% | -18.8 | Critical |
| Tools | 14 | 59.4% | F | 80% | -20.6 | Critical |
Standards Coverage: 6/7 complete. Missing: coditect-standard-tools.md
1. AGENTS (766) — Grade A (91.4%) — MAINTENANCE
Grade Distribution
A=473 (61.7%), B=290 (37.9%), C=1, D=1, F=1
Systematic Gaps (Bottom Attributes)
| Attribute | Pass Rate | Remediation |
|---|
| C5_limitations (When NOT to Use) | 21.5% | Add ## When NOT to Use section with 3-5 anti-use-cases |
| E3_anti_patterns (table) | 23.0% | Add ## Anti-Patterns (Avoid) table with Problem/Solution columns |
| E4_success_criteria | 45.4% | Add ## Success Output + ## Failure Indicators sections |
| C6_integration | 58.1% | Add ## Related Components with cross-references |
| D2_code_examples | 67.9% | Add fenced code blocks with language tags |
Bottom Components
| Component | Score | Key Fix |
|---|
| rust-expert-developer | 56.0% (F) | Missing role statement, responsibilities, limitations |
| production-folder-auditor | 67.3% (D) | Missing integration, anti-patterns |
| markdown-mermaid-cleaner | 70.3% (C) | Missing code examples, success criteria |
- 3 components need attention (F+D+C)
- Bulk fix: Script to add "When NOT to Use" and "Anti-Patterns" boilerplate to all agents missing them
2. HOOKS (109) — Grade B (84.0%) — MAINTENANCE
Grade Distribution
A=40 (36.7%), B=38 (34.9%), C=21 (19.3%), D=10 (9.2%), F=0
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| E3_usage_documented | 44.0% | Add YAML frontmatter in docstring with usage example |
| A2_exit_codes | 48.6% | Ensure exit(0) for success, exit(2) for blocking |
| D3_config_documented | 56.9% | Add settings.json config example in docstring |
| B1_input_validation | 59.6% | Add try/except around json.loads(sys.stdin.read()) |
| A4_function_structure | 78.0% | Refactor inline code into named functions |
Bottom Components
| Component | Score | Key Fix |
|---|
| post-cx-backup | 60.0% (D) | Missing input validation, config docs |
| pre-commit-markdown-check | 60.0% (D) | Missing exit codes, usage docs |
| pre-push-submodule-check | 60.0% (D) | Missing function structure |
| documentation-sync | 65.0% (D) | Missing usage documentation |
| post-commit-component-sync | 65.0% (D) | Missing config documentation |
- 10 components at Grade D need attention
- Focus: Add YAML frontmatter docstrings and config examples
3. SCRIPTS (433) — Grade C (72.9%) — MEDIUM PRIORITY
Grade Distribution
A=36 (8.3%), B=92 (21.2%), C=129 (29.8%), D=123 (28.4%), F=53 (12.2%)
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| D2_cleanup | 19.2% | Add cleanup handlers (tempfiles, locks) in try/finally |
| B3_verbose_flag | 30.0% | Add --verbose / -v argparse flag |
| C1_input_validation | 32.3% | Add path/data validation before processing |
| B2_help_flag | 36.7% | Add -h/--help via argparse (usually automatic) |
| B4_dry_run | 37.2% | Add --dry-run / -n flag for destructive scripts |
| D4_exit_code | 50.8% | Ensure non-zero exit on failure (sys.exit(1)) |
| D3_logging | 63.0% | Add structured logging with levels |
| B1_argparse | 74.1% | Replace sys.argv parsing with argparse |
Bottom Components
| Component | Score | Key Fix |
|---|
| fix-token-limit-hook | 41.7% (F) | Missing argparse, validation, cleanup |
| batch-8-commit-command | 41.7% (F) | Missing CLI interface entirely |
| skill_builder | 45.0% (F) | Missing error handling, docs |
| pruning | 50.0% (F) | Missing argparse, validation |
| invokes_edge_builder | 50.0% (F) | Missing CLI flags, cleanup |
- 176 scripts at D+F need work (53 F-grade, 123 D-grade)
- Bulk fix approach: Script to add argparse boilerplate + --verbose/--dry-run flags
- Content fix: Add input validation and cleanup handlers
4. COMMANDS (363) — Grade D (69.5%) — HIGH PRIORITY
Grade Distribution
A=11 (3.0%), B=21 (5.8%), C=117 (32.2%), D=166 (45.7%), F=48 (13.2%)
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| B3_argument_hint | 3.3% | Add argument-hint: field to YAML frontmatter |
| A3_name_matches_file | 10.5% | Add/fix name: field matching filename |
| B2_description_present | 11.6% | Add description: field to YAML frontmatter |
| D1_related_components | 13.2% | Add ## Related Components section |
| C2_arguments_table | 40.5% | Add arguments table (name, type, default, description) |
Bottom Components
| Component | Score | Key Fix |
|---|
| sl | 31.0% (F) | Missing nearly all frontmatter fields |
| naming-check | 45.3% (F) | Missing description, argument-hint, arguments table |
| organize | 45.3% (F) | Missing description, argument-hint |
| readme-gen | 45.3% (F) | Missing description, argument-hint |
| structure | 45.3% (F) | Missing description, argument-hint |
- 214 commands at D+F (the majority!)
- Root cause: Most commands lack
name:, description:, and argument-hint: in frontmatter
- Bulk fix: Script to extract name from filename, generate description from title/content, add argument-hint
- Content fix: Add Related Components and Arguments tables
5. WORKFLOWS (7) — Grade D (65.1%) — HIGH PRIORITY
Grade Distribution
A=0, B=0, C=3 (42.9%), D=3 (42.9%), F=1 (14.3%)
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| E1_common_issues | 28.6% | Add ## Troubleshooting / ## Common Issues section |
| E2_debug_approach | 28.6% | Add debugging steps for when workflow fails |
| A1_prerequisites_section | 42.9% | Add ## Prerequisites section listing requirements |
| B2_expected_output | 42.9% | Add expected output for each step |
| C3_variant_paths | 42.9% | Document alternative paths/variations |
| A2_inputs_specified | 57.1% | List required inputs explicitly |
| B1_numbered_steps | 57.1% | Convert prose to numbered step sequences |
Bottom Components
| Component | Score | Key Fix |
|---|
| transcript-normalize | 45.8% (F) | Missing prerequisites, troubleshooting, expected output |
| component-database-maintenance | 61.7% (D) | Missing troubleshooting, variant paths |
| disaster-prevention | 61.7% (D) | Missing debug approach, inputs |
- Small set — can be manually enhanced
- Each workflow needs: Prerequisites, numbered steps with expected output, troubleshooting
6. SKILLS (430) — Grade D (61.2%) — CRITICAL PRIORITY
Grade Distribution
A=13 (3.0%), B=104 (24.2%), C=22 (5.1%), D=9 (2.1%), F=282 (65.6%)
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| B4_toc_if_long | 5.6% | Add ## Table of Contents for skills >100 lines |
| A3_description_valid | 32.6% | Add/fix description: in YAML frontmatter |
| A5_third_person | 32.6% | Rewrite description to third-person (no "you", starts with verb) |
| A1_name_matches_dir | 33.7% | Add/fix name: field to match directory name |
| A2_name_format | 34.0% | Ensure name is lowercase-hyphenated, under 64 chars |
| B3_level3_resources | 43.3% | Split large skills into separate resource files |
| D1_dir_matches_name | 48.4% | Ensure directory name matches skill name in frontmatter |
| C5_principles | 69.3% | Add ## Principles or ## Anti-Patterns section |
Bottom Components (282 at Grade F!)
| Component | Score | Key Fix |
|---|
| build-deploy-workflow | 40.9% (F) | Missing all frontmatter fields, no steps |
| business-document-generation | 40.9% (F) | Missing frontmatter, code examples |
| install-script-lifecycle | 40.9% (F) | Missing frontmatter fields |
| iot-patterns | 40.9% (F) | Missing name, description in YAML |
| kubernetes-troubleshooting | 40.9% (F) | Missing frontmatter fields |
- 282 skills at Grade F — largest remediation challenge
- Root cause: Most skills have malformed/incomplete YAML frontmatter (missing
name:, description:)
- Bulk fix approach:
- Script to auto-populate
name: from directory name
- Script to auto-populate
description: from first paragraph
- Script to rewrite descriptions to third-person
- Script to add TOC for skills >100 lines
- Content fix: Add code examples and principles sections
Grade Distribution
A=1 (7.1%), B=1 (7.1%), C=3 (21.4%), D=3 (21.4%), F=6 (42.9%)
Systematic Gaps
| Attribute | Pass Rate | Remediation |
|---|
| E1_common_issues | 14.3% | Add ## Troubleshooting section |
| A1_capabilities | 28.6% | Add ## Features / ## Capabilities section |
| C2_data_flows | 35.7% | Add architecture/data flow documentation |
| D1_installation | 42.9% | Add ## Setup / ## Installation instructions |
| C1_system_design | 57.1% | Add ## Architecture section |
| D2_dependencies | 64.3% | List all dependencies explicitly |
| B3_integration_patterns | 71.4% | Add integration examples |
| E2_debug_resources | 71.4% | Add debug/support references |
Bottom Components
| Component | Score | Key Fix |
|---|
| transcript-normalization | 18.3% (F) | Missing nearly everything |
| mcp-backup | 36.7% (F) | Missing capabilities, architecture, troubleshooting |
| mcp-context-graph | 42.5% (F) | Missing capabilities, installation |
| mcp-impact-analysis | 45.0% (F) | Missing capabilities, data flows |
| mcp-call-graph | 52.5% (F) | Missing troubleshooting, installation |
- BLOCKER: No
coditect-standard-tools.md exists — must create first
- Most MCP tools lack README.md with capabilities, architecture, and troubleshooting
- Each tool needs: Features list, architecture diagram, setup steps, troubleshooting
Phase 1: Quick Wins (Week 1)
| Action | Impact | Effort | Components |
|---|
Create coditect-standard-tools.md | Unblocks tools remediation | Low | 1 standard |
| Fix 7 workflows (add prerequisites, troubleshooting) | +15% avg | Low | 7 |
| Fix 3 failing agents | 100% A+B rate | Low | 3 |
| Fix 10 D-grade hooks (add YAML frontmatter) | +4% avg | Low | 10 |
Phase 2: Bulk Automation (Week 2)
| Action | Impact | Effort | Components |
|---|
Script: Add name: + description: to skill frontmatter | +20% skills avg | Medium | 282 |
Script: Add name: + description: + argument-hint: to command frontmatter | +15% commands avg | Medium | 214 |
| Script: Add argparse + --verbose/--dry-run to scripts | +10% scripts avg | Medium | 176 |
Phase 3: Content Enhancement (Week 3-4)
| Action | Impact | Effort | Components |
|---|
| Add code examples + TOC to skills | +10% skills avg | High | 282 |
| Add arguments tables + related components to commands | +8% commands avg | High | 214 |
| Add capabilities, architecture, troubleshooting to tools | +20% tools avg | Medium | 14 |
| Add input validation + cleanup to scripts | +5% scripts avg | High | 176 |
Phase 4: Excellence (Ongoing)
| Action | Impact | Effort | Components |
|---|
| Add anti-patterns + success criteria to agents | +5% bonus | Low | 766 |
| Add third-person descriptions to skills | +5% skills avg | Medium | 282 |
| Add config documentation to hooks | +3% hooks avg | Low | 62 |
Automation Scripts Needed
| Script | Purpose | Target |
|---|
fix-skill-frontmatter.py | Auto-populate name/description from directory/content | 282 F-grade skills |
fix-command-frontmatter.py | Auto-populate name/description/argument-hint | 214 D+F commands |
fix-script-cli.py | Add argparse boilerplate + standard flags | 176 D+F scripts |
fix-agent-sections.py | Add When NOT to Use + Anti-Patterns boilerplate | 600+ agents |
fix-tool-readme.py | Generate README.md template for tool directories | 9 D+F tools |
Success Criteria
| Milestone | Target | Metric |
|---|
| Week 1 | All types >= D (60%) | Tools 59.4% → 65%+ |
| Week 2 | All types >= C (70%) | Skills 61.2% → 70%+, Commands 69.5% → 75%+ |
| Week 4 | All types >= B (80%) | Framework-wide compliance with ADR-161 |
| Ongoing | Maintain B+ (85%+) | qa-grade-gate hook prevents regression |