shadowx4fox/architecture-explorer-headers

Architecture Explorer Headers — Backfill Skill

When This Skill Is Invoked

Manually activated when users want to add or refresh <!-- EXPLORER_HEADER --> blocks across architecture docs. This is a maintenance workflow, not part of the normal authoring loop. Use it:

• After upgrading to v3.14.0+ on a project whose docs were authored under earlier versions.
• When the architecture-explorer agent is routing files to irrelevant_files[] despite the file being clearly relevant — usually a missing or stale header.
• After a major refactor that renamed components or added technologies, where existing headers have drifted.

NOT activated for:

• Routine architecture authoring (use architecture-docs).
• Component file creation or update — architecture-component-guardian is the first-class writer of EXPLORER_HEADER blocks for docs/components/**/*.md (L1 descriptors and L2 containers) at create/update/migrate time. This backfill skill must NOT be used to fill gaps left by the guardian; reach for it only on legacy docs/NN-*.md files or to repair drift caused by external edits.
• ADR creation (use architecture-definition-record).

ARCHITECTURE.md at the project root is never touched by this skill — it is a navigation index and the explorer reads it in full.

---

Activation Forms

• /skill architecture-explorer-headers — interactive: scan, present plan, ask before writing.
• /regenerate-explorer-headers — slash-command alias.
• /regenerate-explorer-headers --force — overwrite existing headers (default behaviour skips files that already have one).
• /regenerate-explorer-headers --dry-run — list what would change, write nothing.
• /regenerate-explorer-headers <path-glob> — restrict to a subset (e.g. docs/components/payment-service/**).

---

Workflow

Phase 0 — Resolve Plugin and Project Roots

1. Resolve plugin_dir: Glob for **/skills/architecture-explorer-headers/SKILL.md and strip the suffix; or read .claude/settings.json for extraKnownMarketplaces. Same approach as architecture-compliance.
2. Confirm project_root: the current working directory. Verify ARCHITECTURE.md exists at the root — if not, abort with ARCHITECTURE.md not found at project root. This skill operates on architecture documentation.

Phase 1 — Inventory

bun [plugin_dir]/skills/architecture-explorer-headers/utils/header-cli.ts list <project_root>

The CLI emits a JSON array, one entry per candidate file:

[
  { "path": "docs/01-system-overview.md", "has_header": false, "h1": "System Overview", "byte_size": 14820 },
  { "path": "docs/08-scalability-and-performance.md", "has_header": true, "h1": "Scalability & Performance", "byte_size": 18234 },
  { "path": "docs/components/payment-service.md", "has_header": false, "h1": "Payment Service", "byte_size": 9120 }
]

Parse it. Bucket files into:

• needs_header — has_header === false and the path is in scope (matches the <path-glob> argument if provided).
• already_has_header — has_header === true. With --force, treat these as needs_header too. Without --force, skip.
• skipped — outside scope, or ARCHITECTURE.md (excluded by the CLI).

If the inventory is empty, report No docs need explorer headers. and exit.

Phase 2 — Present Plan

Show the user a one-screen plan:

Architecture Explorer Headers — Backfill Plan

Project: <project_root>
Scope:   <path-glob or "all docs">
Mode:    <add-missing | --force | --dry-run>

Files to update (N):
  - docs/01-system-overview.md     (no header)
  - docs/03-architecture-layers.md (no header)
  - docs/components/payment-service.md (no header)
  ...

Files skipped (M):
  - docs/08-scalability-and-performance.md (already has header — pass --force to overwrite)
  - ARCHITECTURE.md (project root index — exempt by design)

Proceed? (yes / no / edit-scope)

Wait for confirmation. On --dry-run skip the prompt and end after this report.

Phase 3 — Generate and Insert Headers

For each file in needs_header:

Step 3.1 — Read the full file. You need the body to extract accurate metadata; do NOT cap reads here. (This skill is the inverse of the explorer — you are creating the metadata the explorer will later sample.)

Step 3.2 — Extract metadata. Build the EXPLORER_HEADER content from the file's actual content:

• key_concepts — 5–15 domain terms that recur in the doc. Pull from H2/H3 headings, bold terms, table headers, and frequently-occurring capitalized phrases. Avoid generic words ("system", "approach", "data"); favor specific ones ("SLO", "MTTR", "idempotency", "circuit breaker"). Downstream skills (compliance, analysis, dev-handoff) filter the explorer's manifest by these terms when deciding which files to read — concrete, domain-specific vocabulary surfaces relevant docs; generic vocabulary surfaces nothing.
• technologies — concrete tools/products named in the doc (Prometheus, AWS, PostgreSQL 16, Spring Boot 3.3, etc.). Skip generic terms ("database", "API"). Preserve version numbers.
• components — kebab-case component names referenced in the doc. Match docs/components/<NN>-<slug>.md filenames. For component files themselves, use component_self: <slug> instead.
• scope — one short sentence (≤120 chars) describing what the doc covers and what it does NOT. Read the doc's intro paragraph to source this.
• related_adrs — ADR identifiers (ADR-NNN) referenced in the doc body or footer.
• component_self (component files only) — the component's kebab-case slug, derived from filename.
• component_type (component files only) — extract from **Type:** field in the file. If absent, omit the field.

Step 3.3 — Compose the 30-second summary blockquote. One paragraph (≤300 chars) that complements the machine-readable header. Read for a reader who has 30 seconds to decide whether to read the full doc.

Step 3.4 — Insert via Edit.

Find the H1 line (^# ) in the file. The insertion goes immediately after the H1 and the blank line that should follow it.

# <existing H1>

<!-- EXPLORER_HEADER
key_concepts: <comma-separated>
technologies: <comma-separated>
components: <comma-separated>     # OR `component_self:` + `component_type:` for component files
scope: <one sentence>
related_adrs: <ADR-NNN, ADR-NNN>
-->

> <30-second summary paragraph>

<existing body>

Use the Edit tool (not Write) so you preserve the rest of the file byte-for-byte.

Step 3.5 — Validate.

bun [plugin_dir]/skills/architecture-explorer-headers/utils/header-cli.ts validate <abs_path>

Exit code 0 = header parses cleanly and includes all required fields. Exit code 1 = malformed; revert the Edit, log the error, continue with the next file.

Phase 4 — Report

Print a summary table:

Architecture Explorer Headers — Backfill Complete

Updated:   N files
Skipped:   M files (already had headers; pass --force to overwrite)
Failed:    K files (malformed header — Edit reverted)

Updated files:
  ✅ docs/01-system-overview.md
  ✅ docs/03-architecture-layers.md
  ✅ docs/components/payment-service.md
  ...

Failed files:
  ❌ docs/components/legacy-thing.md — header validation: missing 'scope' field

Suggest a follow-up: Want me to /schedule an agent to re-run this monthly? Stale headers degrade explorer accuracy over time.

---

Anti-Patterns

1. Don't generate headers from imagination. Every field MUST come from the file's actual content. If a technology isn't named in the doc, don't list it. The explorer's classification is only as accurate as the header's truthfulness.
2. Don't touch ARCHITECTURE.md. It's a navigation index, exempt by design. The CLI's list subcommand excludes it.
3. Don't run with --force on a freshly-tuned project. Operators may have hand-curated headers; --force wipes that work. Default mode (skip-existing) is safe.
4. Don't skip the validation step. A malformed header (missing field, broken comment fence) is worse than no header — it actively misleads the parser. Always run header-cli.ts validate and revert on failure.
5. Don't widen the scope past docs/ and docs/components/. Headers are not for ADRs (ADRs have their own structure that the explorer reads natively) or for archive/v*/ snapshots (those are immutable).

---

Permissions

This skill needs the same Read, Edit, and Bash([plugin_dir]/skills/architecture-explorer-headers/utils/header-cli.ts list/validate) permissions as architecture-docs. The pre-configured .claude/settings.json.example already covers them.

---

Skill Version: 1.2.0 (v3.19.1 — drops --session mode + session editlog integration; the underlying PostToolUse hook had been silently broken since v3.14.1) Specialization: Backfill EXPLORER_HEADER blocks into legacy architecture docs