tdms-ecosystem-audit

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.

1. CHECK for saved progress first (MUST)
2. ALWAYS run the script first (MUST)
3. ALWAYS display the dashboard (MUST)
4. Use conversational Q&A for decisions (MUST) — NEVER use AskUserQuestion
5. SAVE progress after every decision (MUST)
6. Show patch suggestions inline (SHOULD)
7. Create TDMS entries (MUST) for deferred findings
8. 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

1. Run the audit script:

node .claude/skills/tdms-ecosystem-audit/scripts/run-tdms-ecosystem-audit.js

2. Parse the v2 JSON output from stdout (progress goes to stderr).

3. 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

4. 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