generate-adrs — ContextAtlas ADR generation via Claude Code session

When to use this skill

You're running ContextAtlas ADR generation inside your Claude Code session. User invoked you via /generate-adrs slash command, OR via contextatlas project context surfacing in their session.

This is THE canonical entry point for subscription-bounded ADR generation. The contextatlas generate-adrs CLI binary uses Anthropic API direct generation (different cost model; not this skill's concern). Per ADR-02 v0.7 amendment §Decision: generation has two entry points; each entry point uses the appropriate cost model for its invocation context.

If user is asking how to generate ADRs:

• They're working in Claude Code session right now → invoke this skill
• They want CLI / CI/CD / scripting workflow → tell them to use

contextatlas generate-adrs from terminal (uses Anthropic API direct; requires ANTHROPIC_API_KEY env var)

What this skill does

Walks the codebase, identifies non-obvious architectural decisions, and writes canonical ContextAtlas-format ADRs to docs/adr/ in the configured repo. Supports optional reference-context input (the user's existing architectural documentation in any format — Markdown ADRs, reStructuredText DEPs, Confluence exports, architectural commentary) which informs ADR generation as PROMPT INPUT (not direct extraction substrate).

The workflow has three MANDATORY phases (A → B → C). Each phase has explicit completion criteria; do not advance until the prior phase is substantively complete.

Step 1 — Load the canonical generate-adrs prompt via Read tool

Read tool against: .contextatlas/prompts/generate-adrs.md (cwd-relative).

This file is generated by contextatlas init from the canonical GENERATE_ADRS_PROMPT constant at src/generation/prompt.ts. The user repo must have run contextatlas init before invoking this skill. If the file does not exist at this path, instruct the user to run contextatlas init before retrying.

DO NOT improvise the generate-adrs prompt from training-data familiarity. The legacy contextatlas show-generate-prompt CLI subcommand was removed entirely at v0.7 Step 2.3.b.0 — there is no alternative path. Use Read tool against the artifact.

Phase A — Comprehensive codebase investigation (MANDATORY before Phase B)

Before writing ANY ADR, conduct substantive investigation of the codebase for each architectural decision candidate. The discipline is investigative-depth-per-decision-candidate — NOT a fixed file- read count. Small focused codebases may surface decisions from a modest read footprint; large codebases require commensurately more exploration.

For each candidate decision you identify:

1. Read the load-bearing implementation files — actual function

bodies, class definitions, interface declarations, error handling paths. NOT just symbol-name enumeration from a directory listing.

1. Note specific line numbers for the symbols and patterns you

plan to cite in the ADR.

1. Track cross-file dependencies and patterns — a decision

rarely lives in one file; the ADR must surface the full surface area.

1. Identify alternatives visible in the codebase — commented-

out code, "TODO: consider X" patterns, abandoned-approach commits, comparison tables in comments. These become the alternatives-considered enumeration in the ADR's Rationale.

If you also have reference context (--reference-context <path> provided), walk it with Scope γ' multi-format support (.md + .rst; Nygard / ADR-NN / Date naming conventions; recursive depth-2) per v0.7 Step 2.1.a substrate. Reference context informs WHAT decisions to capture and provides historical context for the Rationale + Consequences sections.

Phase A complete when: you can name each architectural decision candidate with specific line-level grounding for the symbols and patterns each ADR will cite. Proceed to Phase B.

Phase B — ADR writing using canonical prompt + investigation

Apply the GENERATE_ADRS_PROMPT (loaded at Step 1) to your Phase A investigation. Produce JSON output matching the schema:

{
  "adrs": [
    {
      "number": 1,
      "title": "<short noun-phrase title>",
      "symbols": ["<canonical symbol names>"],
      "severity_summary": "hard|soft|context",
      "markdown_body": "<full ADR markdown body>"
    }
  ]
}

RESPOND WITH THE JSON LITERAL DIRECTLY. Do NOT write a Python/ JS/shell script to encode the ADRs as data literals. Reason through the Phase A investigation + canonical prompt; produce the JSON as your direct textual response.

Each ADR's markdown_body must follow the prompt's canonical template (Context + Decision + Rationale + Consequences) with the depth invariants the prompt prescribes:

• Substantive Context paragraphs establishing stakes
• Decision section citing specific symbols with line numbers
• Rationale enumerating ≥2 distinct named alternatives with text

beyond labels

• Consequences listing named failure modes + review invariants
• ≥1 fenced code block per ADR illustrating the decision

Validate JSON parses + each ADR has required fields. Drop malformed ADRs (log warning); don't fail the whole run.

Write each ADR to docs/adr/ADR-NN-<title-slug>.md using the Write tool. Number = entry's number field; slug derived from title. Include the YAML frontmatter block (---) with title, severity, symbols fields.

Phase C — MANDATORY validate-adrs gate

After writing all ADRs (Phase B), invoke contextatlas validate-adrs via Bash. This CLI subcommand mechanically verifies each ADR against canonical depth-floor invariants (frontmatter + canonical sections + ≥2 symbol-with-line citations + ≥2 named alternatives + ≥1 code block + ≥3 Rationale items + ≥3 Consequences items + 600-line ceiling).

If exit code is non-zero, read stderr carefully — it contains per-ADR specific remediation. For each failing ADR:

1. Identify which depth-floor invariants failed
2. Re-investigate the codebase IF the failure suggests insufficient

Phase A depth (e.g., "≥2 symbol-with-line-number citations" means you need to add concrete line-level grounding)

1. Re-write the ADR addressing each specific failure
2. Re-invoke contextatlas validate-adrs

Loop until exit code 0. DO NOT report Skill workflow success while any ADR fails validate-adrs.

Reference-context handling

When the user provides reference context via --reference-context <path> flag (CLI) or via skill argument / conversational context (Skills surface):

• Walk the reference path with Scope γ' multi-format support (.md +

.rst; 3 naming conventions; recursive depth-2) per v0.7 Step 2.1.a substrate.

• Concatenate reference context contents into the prompt input

(after the codebase inventory; before the trailing ---).

• Token budget: reference context content is concatenated into

prompt input verbatim per γ user-configurable scope approach. Soft warning emits if reference context exceeds 500k tokens (informational; generation proceeds). Claude Opus 4.7 supports 1M context window; ~800k available for reference context after reserving for codebase inventory + prompt + ADR output. User controls authoritative-substrate boundary via --reference-context <path> flag scope (CLI) OR skill argument (Skills surface). Matches v0.7 user-configured-root philosophy per Step 2.1.a substantive framing.

When to skip reference context

Reference context adds substantive value when user has thoughtful existing architectural documentation in heterogeneous format (Django DEPs, Confluence exports, internal wikis, RFC repos). Reference context adds noise when source is sparse, inconsistent, or already in canonical format.

When to skip reference context:

• User's existing documentation is already in ContextAtlas ADR

format → no migration needed; pure codebase generation suffices.

• Codebase has no existing architectural documentation →

cold-start path (this is the common case for early v1.0 cohort users).

• Reference context source is unreliable / known-stale → defer

to code-only generation.

Cost model

Claude Code session tokens (subscription-bounded). Reports cost_usd: 0.0 + cost_model: "subscription-bounded" in the generation summary. No Anthropic API key required. Per ADR-02 v0.7 §Consequences cost-accounting-reflects-entry-point lock.

Tool usage

This skill uses Claude Code session tools to perform generation:

• Read for the canonical generate-adrs prompt artifact

(.contextatlas/prompts/generate-adrs.md) + source file content + reference-context content

• Write for ADR file persistence at docs/adr/
• Bash for two purposes:
• Listing files (find / ls / glob for source + reference-context

discovery)

• MANDATORY workflow gate (Phase C): invoking `contextatlas

validate-adrs` to verify ADRs conform to canonical depth-floor invariants. Non-zero exit code MUST trigger re-investigate + re-write + re-validate loop; workflow blocks until all ADRs pass.

The legacy contextatlas show-generate-prompt CLI subcommand was removed at v0.7 Step 2.3.b.0; the canonical prompt is only available via Read tool against the artifact.

Bundled helper scripts deferred to v0.8+ per v0.7 ship scope.

Failure modes

• `.contextatlas/prompts/generate-adrs.md` missing: user has

not run contextatlas init in this repo (or init failed to copy artifacts). Surface remediation: instruct user to run contextatlas init and retry. Do NOT improvise the prompt.

• `contextatlas validate-adrs` exits non-zero (Phase C gate):

read stderr carefully — it contains per-ADR specific remediation (e.g., "ADR-05 has only 1 named alternative; expected ≥2 with substantive text content"). For each failing ADR, identify the failing invariants; re-investigate the codebase if depth is insufficient; re-write the ADR; re-invoke validate-adrs. Loop until exit code 0. DO NOT report Skill workflow success while any ADR fails the gate.

• Source file unreadable: log warning; skip; continue.
• Reference-context path doesn't exist: fail loudly with

message; surface to user (they probably typoed the path).

• **Reference-context exceeds soft-warning threshold (500k

tokens)**: emit informational warning; proceed with generation. Substantive message includes measured token count + available context window math + proceed-anyway framing. If actual API call exceeds 1M context window, Claude API returns error which ContextAtlas surfaces with remediation guidance (substantively unlikely at v0.7 soft-warning threshold + reasonable codebase scale; honest-scope-acknowledgment if encountered).

• Malformed JSON output: log warning with first 200 chars;

retry once; then surface failure to user.

• Schema validation failure on individual ADRs: drop malformed

(per-ADR granularity); preserve valid ADRs from same response.

• Write failure to docs/adr/: fail loudly per CLAUDE.md

"actionable error messages" discipline.