| name | tdms-ecosystem-audit |
| description | Comprehensive diagnostic of the Technical Debt Management System — 16 categories
across 5 domains with composite health scoring, trend tracking, patch suggestions,
and interactive finding-by-finding walkthrough. Covers all 37 TDMS scripts, data
files, pipeline integrity, and reporting accuracy.
|
Document Version: 1.0
Last Updated: 2026-02-23
Status: ACTIVE
TDMS Ecosystem Audit
Deep diagnostic of the entire Technical Debt Management System — pipeline
scripts (scripts/debt/), data files (MASTER_DEBT.jsonl,
raw/deduped.jsonl), views, metrics, sprint integration, and roadmap
cross-references. Produces per-category scores, a composite health grade (A-F),
trend tracking across runs, and an interactive walkthrough with patch
suggestions.
Invocation: /tdms-ecosystem-audit
When to use: When you want to understand the overall health of the TDMS
pipeline, identify data quality issues, sync drift between master and deduped
files, broken roadmap cross-references, or metrics accuracy problems.
Complementary with the verification queue workflow (that verifies individual
DEBT items; this skill audits the SYSTEM itself).
When to Use
- Tasks related to tdms-ecosystem-audit
- User explicitly invokes
/tdms-ecosystem-audit
When NOT to Use
- When the task doesn't match this skill's scope -- check related skills
- When a more specialized skill exists for the specific task
CRITICAL RULES (Read First)
Read .claude/skills/_shared/ecosystem-audit/CRITICAL_RULES.md and follow all
8 rules. The rules below are summaries — the shared file is authoritative.
- CHECK for saved progress first (MUST)
- ALWAYS run the script first (MUST)
- ALWAYS display the dashboard (MUST)
- Use conversational Q&A for decisions (MUST) — NEVER use AskUserQuestion
- SAVE progress after every decision (MUST)
- Show patch suggestions inline (SHOULD)
- Create TDMS entries (MUST) for deferred findings
- Save decisions (MUST) to session log
Compaction Guard
Read .claude/skills/_shared/ecosystem-audit/COMPACTION_GUARD.md for the full
compaction guard protocol (state file schema, resume, save, cleanup).
State file path: .claude/tmp/tdms-audit-progress.json
Phase 1: Run & Parse
- Run the audit script:
node .claude/skills/tdms-ecosystem-audit/scripts/run-tdms-ecosystem-audit.js
-
Parse the v2 JSON output from stdout (progress goes to stderr).
-
Create a session decision log file:
- Path:
.claude/tmp/tdms-audit-session-{YYYY-MM-DD-HHMM}.jsonl
- Create
.claude/tmp/ directory if it doesn't exist
-
Save initial progress state to .claude/tmp/tdms-audit-progress.json with
currentFindingIndex: 0, the full findings data, score, and grade.
Phase 2: Dashboard Overview (compact)
Present a compact header with composite grade and domain breakdown:
TDMS Ecosystem Health: {grade} ({score}/100) | Trend: {sparkline} ({delta})
{errors} errors · {warnings} warnings · {info} info | {patches} patch suggestions
┌──────────────────────────────────┬───────┬──────────┬──────────────┐
│ Category │ Score │ Rating │ Trend │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D1: Pipeline Correctness │ │ │ │
│ Script Execution Order │ {s} │ {rating} │ {trend} │
│ Data Flow Integrity │ {s} │ {rating} │ {trend} │
│ Intake Pipeline │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D2: Data Quality & Deduplication │ │ │ │
│ Dedup Algorithm Health │ {s} │ {rating} │ {trend} │
│ Schema Compliance │ {s} │ {rating} │ {trend} │
│ Content Hash Integrity │ {s} │ {rating} │ {trend} │
│ ID Uniqueness & Ref Integrity │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D3: File I/O & Safety │ │ │ │
│ Error Handling Coverage │ {s} │ {rating} │ {trend} │
│ Master-Deduped Sync │ {s} │ {rating} │ {trend} │
│ Backup & Atomicity │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D4: Roadmap Integration │ │ │ │
│ Track Assignment Rules │ {s} │ {rating} │ {trend} │
│ ROADMAP-DEBT Cross-Reference │ {s} │ {rating} │ {trend} │
│ Sprint File Alignment │ {s} │ {rating} │ {trend} │
├──────────────────────────────────┼───────┼──────────┼──────────────┤
│ D5: Metrics & Reporting │ │ │ │
│ View Generation Accuracy │ {s} │ {rating} │ {trend} │
│ Metrics Dashboard Correctness │ {s} │ {rating} │ {trend} │
│ Audit Trail Completeness │ {s} │ {rating} │ {trend} │
└──────────────────────────────────┴───────┴──────────┴──────────────┘
Rating badges: good = "Good", average = "Avg", poor = "Poor"
Then say: "Found N findings to review. Walking through each one
(impact-weighted)..."
Phase 3: Finding-by-Finding Walkthrough
Read .claude/skills/_shared/ecosystem-audit/FINDING_WALKTHROUGH.md for the
full walkthrough protocol (finding card, decisions, patches, delegation,
batching).
Sort findings by impactScore descending (highest impact first). DEBT entries
use source_id: review:tdms-ecosystem-audit-{date}.
Phase 4: Summary & Actions
Read .claude/skills/_shared/ecosystem-audit/SUMMARY_AND_TRENDS.md for the
summary template, trend report template, and verification re-run template.
Write report to .claude/tmp/tdms-audit-report-{YYYY-MM-DD}.md.
Process verification: Run __tests__/ suite:
node --test .claude/skills/tdms-ecosystem-audit/scripts/__tests__/*.test.js
Phase 5: Trend Report (if previous runs exist)
Uses trend report template from SUMMARY_AND_TRENDS.md.
History: .claude/state/tdms-ecosystem-audit-history.jsonl
Category Reference
Domain 1: Pipeline Correctness (20% weight)
| Category | What It Checks |
|---|
| Script Execution Order | consolidate-all.js calls scripts in correct dependency order; no circular deps |
| Data Flow Integrity | Outputs from each stage match expected inputs of next stage |
| Intake Pipeline | All 4 intake scripts produce valid format, write to BOTH master and deduped files |
Domain 2: Data Quality & Deduplication (25% weight)
| Category | What It Checks |
|---|
| Dedup Algorithm Health | 6-pass dedup accuracy, merge relationships, cluster consistency |
| Schema Compliance | All items conform to audit-schema.json; required fields; valid enums |
| Content Hash Integrity | content_hash fields match recomputed SHA256 |
| ID Uniqueness & Ref Integrity | DEBT-XXXX IDs unique; merged_from refs valid; LEGACY_ID_MAPPING clean |
Domain 3: File I/O & Safety (20% weight)
| Category | What It Checks |
|---|
| Error Handling Coverage | All 37 scripts wrap file reads in try/catch; JSON.parse protected |
| Master-Deduped Sync | MASTER_DEBT.jsonl and raw/deduped.jsonl in sync (Session #134 critical bug) |
| Backup & Atomicity | Scripts use temp files for atomic writes; backup before destructive overwrites |
Domain 4: Roadmap Integration (15% weight)
| Category | What It Checks |
|---|
| Track Assignment Rules | roadmap_ref values use valid tracks and phases |
| ROADMAP-DEBT Cross-Reference | DEBT-XXXX refs in ROADMAP.md exist in MASTER_DEBT and vice versa |
| Milestone File Alignment | Milestone assignments match item statuses; no stale refs |
Domain 5: Metrics & Reporting (20% weight)
| Category | What It Checks |
|---|
| View Generation Accuracy | Generated views match MASTER_DEBT aggregation counts |
| Metrics Dashboard Correctness | METRICS.md numbers match computed totals and trend data |
| Audit Trail Completeness | intake-log, dedup-log, resolution-log have entries; valid JSONL |
Benchmarks & Checker Development
Read .claude/skills/_shared/ecosystem-audit/CLOSURE_AND_GUARDRAILS.md for
scoring conventions and the checker development guide.
16 categories. Domain weights: D1=20%, D2=25%, D3=20%, D4=15%, D5=20%.
Data Sources
| Source | Path | Content |
|---|
| TDMS scripts | scripts/debt/*.js | 37 pipeline and utility scripts |
| Canonical data | docs/technical-debt/MASTER_DEBT.jsonl | 4,500+ technical debt items |
| Deduped source | docs/technical-debt/raw/deduped.jsonl | Must stay in sync with master |
| Views | docs/technical-debt/views/*.md | Generated severity/category/status views |
| Metrics | docs/technical-debt/METRICS.md | Dashboard with totals and trends |
| Logs | docs/technical-debt/logs/*.jsonl | Intake, dedup, resolution logs |
| Schema | scripts/config/audit-schema.json | Canonical field definitions |
| ROADMAP | ROADMAP.md | Milestone tracks with DEBT refs |
TDMS Pipeline Architecture
Discovery (extract-*.js)
→ Intake (intake-*.js, sync-sonarcloud.js)
→ Normalization (normalize-all.js)
→ Deduplication (dedup-multi-pass.js, 6 passes)
→ Views (generate-views.js)
→ Metrics (generate-metrics.js)
Critical invariant: MASTER_DEBT.jsonl == raw/deduped.jsonl
(Session #134 bug: generate-views.js reads deduped, overwrites master)
Version History
| Version | Date | Description |
|---|
| 1.2 | 2026-03-25 | Extract shared patterns to _shared/ecosystem-audit/ |
| 1.1 | 2026-02-24 | Add compaction guard for progress persistence |
| 1.0 | 2026-02-23 | Initial implementation |
