Health

Overview

ttm-health audits the integrity of your .taketomarket/ directory. It validates directory structure, reference file completeness, per-campaign state consistency, reference file staleness, campaign velocity, DRIFT-LOG.md integrity, and gate-result coherence, then prints a text report with pass/warn/fail per check category.

Invoke it with ttm-health. It also auto-triggers when potential issues are detected. The workflow only reports problems — it does not self-heal and never modifies any file. State corruption in a long-running multi-campaign project is silent until something breaks, so running health periodically catches drift like a filesystem fsck before it forces a manual rebuild of a campaign's state.

This skill is backed by the bundled script ${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs, which performs the actual audit and emits JSON consumed by the workflow below.

How it works

Health audit workflow for ttm-health. Validates .taketomarket/ directory integrity, reference file completeness, per-campaign state consistency, reference file staleness, campaign velocity, DRIFT-LOG integrity, and gate result consistency. Reports text output with pass/warn/fail per check category. Does NOT self-heal — only reports.

Required reading: ${CLAUDE_PLUGIN_ROOT}/references/context-loading.md.

Constraints

POSITIONING.md is READ-ONLY

Do NOT modify .taketomarket/POSITIONING.md during this workflow.

POSITIONING.md is an architectural invariant. If you detect positioning drift:

• In verify: use the Escalate option to launch ttm-positioning-shift.
• In other workflows: flag the issue and recommend running ttm-positioning-check.

Only ttm-positioning-shift and ttm-init may modify POSITIONING.md.

Diagnostic Only — No Self-Healing

This workflow reports problems. It does NOT fix them. Never modify any file during this workflow. All output is informational. If issues are found, recommend specific commands or manual actions the user should take.

Step 0: First-run inline education

Read .taketomarket/CONFIG.md. Parse first_run_seen (object) and inline_education (boolean, default true).

If inline_education is false: skip this step. Else if first_run_seen.ttm-health is not true, print the explainer below verbatim, then mark this skill as seen:

node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-health

Use this exact check (bash) to decide whether to print: node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-health --raw — the JSON seen field is true once the explainer has run before.

Explainer for ttm-health

ttm-health audits the integrity of your .taketomarket/ directory. It checks that reference files exist and aren't suspiciously empty, flags stale references, validates per-campaign STATE.md against the file system, surfaces DRIFT-LOG anomalies, and reports gate-result inconsistencies. It only reports — it does not self-heal.

Why it matters: state corruption in a long-running multi-campaign project is silent until something breaks. Running health periodically (or letting it auto-trigger on detected issues) catches drift like a filesystem fsck — before it forces a manual rebuild of a campaign's state.

(Canonical source: references/inline-education-blurbs.md. Embedded verbatim because workflows do not @-resolve files at runtime.)

Step: Legacy folder check

Before running the main audit, detect whether the project still uses the legacy .marketing/ state directory and offer migration to the canonical .taketomarket/.

Run the legacy-folder check:

node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" legacy-folder check --raw

Parse the JSON state field:

• legacy: print WARN: Legacy '.marketing/' folder detected. Migration will rename it to '.taketomarket/'. Recommend committing or backing up first (the rename is fast but not reversible from inside the workflow). Then use AskUserQuestion:
  • question: "Migrate .marketing/ to .taketomarket/ now?"
  • options: "Yes, migrate now" / "Skip for now"
  • On Yes: run the migrate command below, then verify .taketomarket/ exists.
  • On Skip: continue to Step 1 with a note that the audit will report .marketing/ paths.
• conflict: print the error below, then halt the workflow.
• current or none: continue silently to Step 1.

Migrate command (run on Yes):

node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" legacy-folder migrate --raw

Conflict error message (printed before halting):

ERROR: Both .marketing/ and .taketomarket/ exist. Manual resolution required.

To resolve:
  1. Compare contents:  diff -r .marketing .taketomarket
  2. Merge any unique files from .marketing/ into .taketomarket/.
  3. Once .taketomarket/ has everything you need, remove the legacy folder:
     rm -rf .marketing
  4. Re-run /ttm-health to confirm.

Step 1: Run Health Audit

takeToMarket > RUNNING HEALTH AUDIT

Run the full health audit via CLI:

HEALTH_JSON=$(node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" health --full --raw)

Parse the JSON output. Expected shape:

{
  "healthy": true/false,
  "checks": [
    { "name": "...", "status": "pass|fail|warn|missing", "path": "...", "detail": "..." }
  ],
  "summary": "N/M checks passed"
}

If the CLI command fails (non-zero exit or invalid JSON), display: "Health audit CLI failed. This may indicate a broken installation. Try running node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" health --full --raw manually to see the error." Then exit.

Step 2: Format Report

takeToMarket > HEALTH REPORT

Group checks by category based on their name prefix or type:

• Structural Integrity — directory existence, required structure
• Reference Files — POSITIONING.md, BRAND.md, ICP.md, etc.
• Campaign State Consistency — per-campaign phase validity, field integrity
• Staleness — files not updated within expected timeframes
• Velocity — campaign progress rate checks
• Drift Log — DRIFT-LOG.md integrity and format
• Gate Consistency — review/verification result coherence

Output Format

## Health Report

### Structural Integrity
  [PASS] .taketomarket/ directory exists
  [PASS] CAMPAIGNS/ directory exists
  [PASS] Required subdirectories present

### Reference Files
  [PASS] POSITIONING.md exists and has content
  [PASS] BRAND.md exists and has content
  [WARN] ICP.md -- not updated in 90+ days (staleness warning)
  [PASS] CHANNELS.md exists and has content
  [PASS] STATE.md exists and has content
  [PASS] CALENDAR.md exists and has content
  [PASS] COMPETITORS.md exists and has content
  [PASS] METRICS.md exists and has content
  [PASS] LEARNINGS.md exists and has content

### Campaign State Consistency
  [PASS] spring-launch -- phase: shipped (valid)
  [FAIL] test-campaign -- invalid phase: bogus
  [PASS] summer-promo -- phase: briefed (valid)

### Staleness
  [WARN] BRAND.md -- last modified 95 days ago
  [PASS] POSITIONING.md -- last modified 12 days ago

### Velocity
  [PASS] Campaign throughput: 2 shipped in last 30 days
  [WARN] No campaigns advanced in 14+ days

### Drift Log
  [PASS] DRIFT-LOG.md format valid
  [PASS] All drift entries have required fields

### Gate Consistency
  [PASS] All reviewed campaigns have verification reports
  [PASS] Fix counts consistent with review results

---

### Overall: HEALTHY (12/14 passed, 2 warnings)

Status determination:

• If healthy is true in CLI output: "HEALTHY"
• If healthy is false: "UNHEALTHY"
• Include total pass count and warning count

Step 3: Recommendations (If Issues Found)

If any checks have warn or fail status, add a Recommendations section:

### Recommendations

**Failures (must fix):**
- <check name>: <specific fix suggestion>
  Run: <suggested command or manual action>

**Warnings (should address):**
- <check name>: <specific suggestion>
  Consider: <suggested action>

Recommendations are advisory only. This workflow does NOT execute any fixes.

If all checks pass with no warnings:

All systems healthy. No action needed.

Success criteria

• Health audit run via CLI (health --full --raw)
• Results grouped by category with clear pass/warn/fail indicators
• Overall healthy/unhealthy status displayed
• Recommendations provided for any issues found
• No files modified (diagnostic command)

What if this doesn't fit?

Looks like ttm-health can't do that yet.

• Want a new skill? ttm-request-skill
• Existing skill needs work? ttm-improve-skill