Back to Guides

A short AI-narrated film with English captions. Pressing play loads the YouTube player. Watch on YouTube

Guide Origin: Official | ArcKit Version: [VERSION]

/arckit:health scans all ArcKit projects for stale research, forgotten ADRs, unresolved review conditions, orphaned artifacts, missing traceability, and version drift -- reporting findings to the console and writing docs/health.json for dashboard integration.

Purpose

Architecture governance produces dozens of artifacts over weeks and months. Without regular health checks, projects accumulate governance debt:

  • Stale research -- vendor pricing and market analysis older than 6 months leads to unreliable procurement decisions
  • Forgotten ADRs -- decisions stuck in "Proposed" status create architectural ambiguity
  • Unresolved conditions -- design reviews approved with conditions that are never formally resolved
  • Orphaned requirements -- requirements not referenced by any ADR, lacking governance coverage
  • Missing traceability -- ADRs without requirement references reduce audit confidence
  • Version drift -- multiple artifact versions where the latest has gone stale
  • Unincorporated external files -- new external documents not yet reflected in architecture artifacts

The /arckit:health command performs a diagnostic scan that:

  • Applies seven detection rules across all projects and artifacts
  • Assigns severity levels (HIGH, MEDIUM, LOW) to each finding
  • Provides specific remediation actions for every issue
  • Writes docs/health.json for dashboard integration with /arckit:pages
  • Runs as a lightweight, repeatable check suitable for daily or weekly use

Inputs

Artifact Requirement What It Provides
Any ARC-* artifacts Required (at least one) Artifacts to scan for governance health issues

Note: This command scans existing artifacts -- it does not require specific artifact types. The more artifacts present, the more comprehensive the health check. If no projects/ directory or ARC-* artifacts exist, the command reports an error with guidance.

Command

/arckit:health

Arguments

Argument Required Default Description
PROJECT No All projects Restrict scan to a single project (e.g., 001-payment-gateway)
SEVERITY No LOW Minimum severity to report: HIGH, MEDIUM, or LOW
SINCE No Today Override staleness baseline date in YYYY-MM-DD format 
# Scan a specific project
/arckit:health PROJECT=001-payment-gateway

# Show only high-severity issues
/arckit:health SEVERITY=HIGH

# Check what will be stale by a future date
/arckit:health SINCE=2026-06-01

Outputs: Console report plus docs/health.json for dashboard integration. No project governance artifacts are created.

Detection Rules

ID Rule Severity Threshold
STALE-RSCH Stale Research HIGH Research documents with last modified date > 6 months old
FORGOTTEN-ADR Forgotten ADR HIGH ADR with "Proposed" status for > 30 days with no review activity
UNRESOLVED-COND Unresolved Conditions HIGH Review with "APPROVED WITH CONDITIONS" where conditions lack resolution evidence
STALE-EXT Unincorporated External Files HIGH External file in external/ newer than all ARC-* artifacts in the same project
ORPHAN-REQ Orphaned Requirements MEDIUM Requirements not referenced by any ADR in the same project
MISSING-TRACE Missing Traceability MEDIUM ADR documents that do not reference any requirement ID
VERSION-DRIFT Version Drift LOW Multiple versions of the same artifact type where the latest is > 3 months old

Workflow Position

The health check is a utility command that sits alongside the main workflow, providing ongoing governance monitoring:

┌──────────────────────────────────────────┐
│         Any artifact creation            │
│  (requirements, ADRs, research, etc.)    │
└────────────────────┬─────────────────────┘
                     │
                     ▼
          ┌─────────────────────┐
          │   /arckit:health    │  (run periodically)
          └──────────┬──────────┘
                     │
        ┌────────────┼────────────────┐
        ▼            ▼                ▼
 ┌────────────┐ ┌──────────┐  ┌──────────────┐
 │  /arckit   │ │ /arckit  │  │   /arckit    │
 │  .research │ │ .adr     │  │.traceability │
 │ (refresh)  │ │ (review) │  │   (fix)      │
 └────────────┘ └──────────┘  └──────────────┘

Best Practice: Run the health check regularly -- before governance gates, after completing a batch of artifacts, or on a schedule using /loop 30m /arckit:health SEVERITY=HIGH.

Example Usage

Scan All Projects

/arckit:health

Scan a Specific Project

/arckit:health PROJECT=001-payment-gateway

High-Severity Issues Only

/arckit:health SEVERITY=HIGH

Future Staleness Check

# What will be stale by June?
/arckit:health SINCE=2026-06-01

Continuous Monitoring

# Run every 30 minutes during architecture sessions
/loop 30m /arckit:health SEVERITY=HIGH

Tips

  • Run before governance gates: Always run a health check before architecture review boards or procurement decisions to ensure no stale data or unresolved conditions are overlooked.

  • Use SEVERITY filtering for triage: Start with SEVERITY=HIGH to address critical issues first, then work down to MEDIUM and LOW findings.

  • Combine with /arckit:pages: The health check writes docs/health.json automatically. Run /arckit:pages afterwards to see health data on your governance dashboard.

  • Not all findings require action: ORPHAN-REQ and MISSING-TRACE findings are flagged for awareness. The architect decides whether ADR coverage or traceability links are needed for each case.

  • Use SINCE for planning: The SINCE parameter lets you preview what will become stale by a future date, useful for scheduling research refreshes or review meetings.

  • This is diagnostic, not analytical: For deeper governance analysis that produces a formal report, use /arckit:analyze instead. The health check is lightweight and repeatable; the analyze command is comprehensive and artifact-producing.

Follow-On Commands

After reviewing health check findings, typical next steps include:

Command Purpose
/arckit:analyze Perform deeper governance analysis producing a formal report
/arckit:conformance Systematic conformance checking against standards
/arckit:research Refresh stale research documents flagged by STALE-RSCH
/arckit:adr Create or review ADRs for forgotten decisions or orphaned requirements
/arckit:traceability Fix missing traceability links between ADRs and requirements

Output Example

========================================
  ArcKit Artifact Health Report
  Scanned: 2026-03-08
  Projects scanned: 3
  Artifacts scanned: 42
========================================

SUMMARY
-------
  HIGH:   3 findings
  MEDIUM: 5 findings
  LOW:    1 finding
  TOTAL:  9 findings

FINDINGS BY TYPE
----------------
  STALE-RSCH:       1
  FORGOTTEN-ADR:    1
  UNRESOLVED-COND:  1
  STALE-EXT:        0
  ORPHAN-REQ:       3
  MISSING-TRACE:    2
  VERSION-DRIFT:    1

PROJECT: 001-payment-gateway
  Artifacts scanned: 15

  [HIGH] STALE-RSCH: research/ARC-001-RSCH-001-v1.0.md
    Last modified: 2025-06-15 (266 days ago)
    Action: Re-run /arckit:research to refresh pricing and vendor data

  [HIGH] FORGOTTEN-ADR: decisions/ARC-001-ADR-003-v1.0.md
    Status: Proposed since 2025-12-01 (97 days without review)
    Action: Schedule architecture review or accept/reject the decision

  [MEDIUM] ORPHAN-REQ: ARC-001-REQ-v2.0.md
    Total requirements: 45
    Requirements not referenced by any ADR: 12
    Examples: FR-015, FR-016, NFR-P-003, NFR-S-008, INT-005
    Action: Review whether these requirements need architectural decisions

PROJECT: 002-data-platform
  Artifacts scanned: 8
  No issues found.

RECOMMENDED ACTIONS (prioritised)
----------------------------------
1. [HIGH] Address 1 stale research document
   Run: /arckit:research for affected projects
2. [HIGH] Review 1 forgotten ADR
   Schedule architecture review meeting
3. [MEDIUM] Check 3 orphaned requirement sets
   Run: /arckit:adr for requirements needing decisions