Brainstorm Beagle

Brainstorm: Ideas Into Specs

Turn a fuzzy idea into a comprehensive, implementation-free project spec through collaborative dialogue.

The output is a standalone spec document — structured enough for any agentic system to consume, clear enough for a human to act on. It captures WHAT and WHY, never HOW.

<hard_gate> Do NOT write any code, create implementation plans, scaffold projects, or take any implementation action. This skill produces a SPEC DOCUMENT only. Every project goes through this process regardless of perceived simplicity — "simple" projects are where unexamined assumptions waste the most work. </hard_gate>

Workflow

Complete these steps in order:

1. Check for a concept brief — if .beagle/concepts/<slug>/brief.md exists for this idea, ingest it and skip most of steps 2-4 (see Concept brief ingestion below) 2. Explore context — read project files, docs, git history, existing specs (lighter pass if a brief is present)

• Prior art check (brownfield only): before specing a feature onto an existing codebase, run a neutral capability sweep to confirm the thing doesn't already exist (see Prior Art Check below). Runs regardless of whether a brief is present.

3. Assess scope — is this one spec or does it need decomposition? 4. Ask clarifying questions — one at a time, follow the thread (few to none if a brief is present) 5. Propose 2-3 directions — high-level product approaches with tradeoffs 6. Draft spec — write the structured spec document 7. Self-review — check for completeness, contradictions, implementation leakage (see references/spec-reviewer.md) 8. User review — present for approval, iterate if needed 9. Write to disk — save to .beagle/concepts/<slug>/spec.md

Brief present? ──→ Yes → Ingest brief (skip most discovery) ──┐
                ──→ No  → Explore context → Assess scope       │
                                            ├─ Too large? → Decompose → Brainstorm first sub-project
                                            └─ Right size? → Clarifying questions ─┘
                                                                                   │
Brownfield? ──→ Yes → Prior art check (neutral capability sweep) ─→ Already exists? ─→ surface, reshape/kill spec
            ──→ No  → skip ─────────────────────────────────────────────────────────────────────┐
                                                                                                  │
Both paths converge → Propose directions → Draft spec → Self-review (fix inline) → User review
                                                                                        ├─ Changes? → Revise
                                                                                        └─ Approved? → Write to concept folder

The terminal state is a written spec. This skill does not transition to implementation, planning, or any other skill. The user decides what to do with the spec.

Concept brief ingestion

If the user invokes brainstorm-beagle on a concept that already has .beagle/concepts/<slug>/brief.md (produced by prfaq-beagle on pass), ingest the brief at step 1 and skip most discovery:

1. Read the brief. Customer, problem, solution concept, stakes, forged decisions, and research pointers are already codified. Do not re-interview the user on these. 2. Skim the PRFAQ reference. Open .beagle/concepts/<slug>/prfaq.md for the Reasoning blocks — they explain what was challenged and why earlier decisions were made. This is context, not content to re-litigate. 3. Open questions become your starting point. The brief's Open Questions section lists what PRFAQ surfaced but did not close. These are what you ask the user about — not customer, problem, or motivation, which are already decided. 4. Proceed to Exploring Directions. Skip Clarifying Questions and Scope Assessment unless the brief is ambiguous about scope itself.

The brief is a context handoff, not a gate. Run your own Self-Review on the spec you produce — brainstorm-beagle remains responsible for implementation-leakage detection, requirement testability, and scope discipline regardless of how much discovery was pre-done upstream.

When there is no brief: proceed through steps 2-9 normally. Not every idea comes from PRFAQ.

The brief does not exempt you from the prior art check. A brief (or the issue behind it) frames the feature as something to build — that framing is exactly the bias the Prior Art Check exists to neutralize. Run the sweep even when ingesting a brief.

Prior Art Check

This step exists because of a specific, expensive failure: drafting a spec that reinvents a capability the codebase already has. It applies whenever the idea is a feature being added to an existing codebase (brownfield). For greenfield ideas with no existing code, skip it.

The failure mode it prevents: An issue or brief frames a feature as new ("we removed the old truncation, design fresh") or simply omits that prior work exists. You — or a subagent you delegate exploration to — inherit that framing, look only where the framing points, confirm the framing, and spec a feature that duplicates code already shipped and tested. The spec then teaches the downstream planner and executor to rebuild something that exists.

The discipline: search neutrally, independent of framing.

1. Run a capability-keyword sweep across the WHOLE workspace — every crate/package/module, not just the directory the issue points at. Search for the capability by its likely names, synonyms, and abbreviations, not the issue's vocabulary. For a truncation feature: grep -riE 'truncat|spill|cap|max_bytes|head_bytes|limit|trim|elide' across all source roots. Cast wide; one matching file kills the assumption. 2. Do not trust "this doesn't exist" claims. Issues and briefs go stale relative to the code — someone may have built the thing after the issue was filed. The issue's "we removed X / X doesn't exist yet" is a hypothesis to disprove with grep, not a fact to inherit. 3. If you delegate exploration to a subagent, give it the neutral sweep, not the narrative scope. Brief it as "grep the entire workspace for these capability keywords and report every hit," not "look in module/foo for where X is written." A scoped brief reproduces the framing bias inside the subagent. Pass the keyword list; do not pass the issue's theory of where the code lives. 4. Surface what you find. If the capability (or a large part of it) already exists:

• Say so plainly, citing the file(s) — "agent/src/spill.rs already implements head-tail capping with a sidecar, and it's tested."
• Reframe the spec around the gap, not the whole feature: extend/fix/wire-up what exists rather than rebuild it. Often this shrinks the spec dramatically or dissolves the need for one.
• Record the discovery as a Key Decision ("Build on existing spill.rs rather than a fresh truncation module") so the downstream planner doesn't re-litigate.

5. Composition check. For each existing mechanism the sweep surfaced, ask: does it sit upstream or downstream in the same data pipeline as the feature, and does it transform (truncate, filter, buffer, reorder, dedupe) the data this feature depends on? If yes, "the mechanism exists" is not the end of the inquiry — its composition with the new feature is the load-bearing question. Record the interaction as a Key Decision ("bash already caps output to 50 KiB upstream; the spill must capture before that cap or it cannot deliver full output") AND tag that decision needs-spike-before-planning, adding to its Rationale: **Spike required:** before plan-lock, verify the upstream/downstream data shape (what it truncates/filters/buffers/reorders/dedupes and whether this feature captures before or after) against this repo and revise this decision if the result diverges from the assumption. A new mechanism that composes wrongly with an existing one in the same pipeline ships broken even though neither piece was reinvented.

This is distinct from Explore context (step 2), which reads to understand the project. The prior art check is adversarial: its job is to disprove the assumption that the feature is new, before that assumption hardens into a spec.

Questioning

You are a thinking partner, not an interviewer. The user has a fuzzy idea — your job is to help them sharpen it.

How to question:

• Start open. Let them dump their mental model. Don't interrupt with structure.
• Follow energy. Whatever they emphasized, dig into that. What excited them? What problem sparked this?
• Challenge vagueness. Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
• Make the abstract concrete. "Walk me through using this." "What does that actually look like?"
• Clarify ambiguity. "When you say Z, do you mean A or B?"
• Know when to stop. When you understand what, why, who, and what done looks like — offer to proceed.

Question mechanics:

• One question per message. If a topic needs more, break it into multiple messages.
• Prefer multiple choice when possible — easier to react to concrete options than open-ended prompts.
• When the user selects "other" or wants to explain freely, switch to plain text. Don't force them back into structured choices.
• 2-4 options is ideal. Never use generic categories ("Technical", "Business", "Other").

What to ask about:

What NOT to ask about:

• Technical implementation details (that's for planning)
• Architecture patterns (that's for planning)
• User's technical skill level (irrelevant — the system builds)
• Success metrics (inferred from the work)
• Canned questions regardless of context ("What's your core value?", "Who are your stakeholders?")

Background checklist (check mentally, not out loud):

• [ ] What they're building (concrete enough to explain to a stranger)
• [ ] Why it needs to exist (the problem or desire driving it)
• [ ] Who it's for (even if just themselves)
• [ ] What "done" looks like (observable outcomes)

When all four are clear, offer to proceed. If the user wants to keep exploring, keep going.

Scope Assessment

Before diving into questions, assess whether the idea is one project or several.

Signs it needs decomposition:

• Multiple independent subsystems ("build a platform with chat, file storage, billing, and analytics")
• No clear ordering dependency between parts
• Would take multiple months of work

When decomposition is needed: 1. Help the user identify the independent pieces and their relationships 2. Establish what order they should be built 3. Brainstorm the first sub-project through the normal flow 4. Each sub-project gets its own spec

For right-sized projects, proceed directly to clarifying questions.

Exploring Directions

After understanding the idea, propose 2-3 high-level directions. These are product directions, not technical architectures.

Good directions:

• "A CLI tool that operates on single files vs. a daemon that watches directories"
• "A focused MVP with just the core loop vs. a broader first version with supporting features"
• "Optimized for speed of use (power users) vs. optimized for discoverability (new users)"

Bad directions (implementation leaking in):

• "React with a REST API vs. HTMX with server-side rendering"
• "PostgreSQL vs. SQLite for storage"
• "Monorepo vs. polyrepo"

Lead with your recommendation and explain why. Present tradeoffs conversationally.

Scope Discipline

Brainstorming naturally generates ideas beyond the current scope. Handle this gracefully:

When the user expands scope mid-brainstorm:

"That's a great idea but it's its own project/phase. I'll capture it in Future Considerations so it's not lost. For now, let's focus on [current scope]."

The heuristic: Does this clarify what we're building, or does it add a new capability that could stand on its own?

Capture deferred ideas in the spec's "Future Considerations" section. Don't lose them, don't act on them.

Implementation Leakage

The spec must never prescribe implementation. This is the hardest discipline.

Exception — constraints: When the user has genuine constraints ("must use PostgreSQL because that's what our infra runs"), those go in the Constraints section with rationale. A constraint is a boundary condition, not a design choice made during brainstorming.

Key Decisions That Rest on Tool Behavior

Some Key Decisions in a spec take the form "we will use feature X of tool Y to achieve Z" (e.g. "compile-time-checked SQL on both backends via sqlx's offline cache", "dual-platform builds via the framework's single-binary target"). These decisions look settled but encode an unverified assumption: that the tool actually behaves the way the docs imply when applied to this codebase.

When recording a Key Decision of this shape, do one of the following — never neither:

1. Cite a worked example. Point at a file in the repo (or a comparable repo on disk) where the tool already does the thing the decision depends on. core/.sqlx/ with N existing query files is a citation; "sqlx supports compile-time checking" from memory is not. 2. Tag the decision `needs-spike-before-planning`. Add an explicit marker to the Rationale: **Spike required:** before plan-lock, verify <specific command/behavior> against this repo and revise this decision if the result diverges from the assumption.

A decision without either is a decision the downstream planner will encode as a fact and the executor will try to build against — and "the docs said it worked" is how a 5-line plan task balloons into a 400-line bash workaround. The spike tag tells the planner to add a Task 0 spike; the citation tells the planner the spike is already implicit in the existing code.

This rule is narrower than implementation leakage. The decision can still be at the WHAT level (e.g. "data must be type-checked at compile time" is WHAT). The rule applies only when the decision's rationale depends on specific tool behavior the user is asserting without evidence.

Spec Format

Use the template in references/spec-template.md. The spec has these sections:

1. Core Value — ONE sentence, the most important thing 2. Problem Statement — what problem, who has it, why now 3. Requirements — must have, should have, out of scope (with reasons) 4. Constraints — hard limits with rationale 5. Key Decisions — decisions made during brainstorming with alternatives considered 6. Reference Points — "I want it like X" moments, external docs, inspiration 7. Open Questions — unresolved items needing future research 8. Future Considerations — ideas that emerged but belong in later phases

Requirements must be concrete and testable:

Self-Review

After drafting the spec, review it for:

1. Placeholders — any TBD, TODO, vague requirements? Fix them. 2. Contradictions — do any sections conflict? Resolve them. 3. Implementation leakage — does any requirement prescribe HOW? Rewrite as WHAT. 4. Untestable requirements — could someone verify this was met? Make it concrete. 5. Missing rationale — do constraints and out-of-scope items explain WHY? Add reasons. 6. Scope — is this focused enough for a single planning cycle? 7. Reinvention (brownfield) — does any must-have rebuild a capability that already exists in the codebase? If the prior art check wasn't run, run it now. Reframe duplicated requirements around the actual gap. 8. Consumer (brownfield) — does any must-have introduce a new externally-facing capability (API surface, command, endpoint, exported contract) that nothing else in the spec consumes? If who/what consumes it isn't named, either name the consumer or move the item to Future Considerations. Unconsumed externally-facing surface is speculative — fix it before presenting.

Fix issues inline. Then present to the user for review.

See references/spec-reviewer.md for the detailed review checklist.

Pass before presenting the draft (user review step): Advance only when every item is honestly yes — not “feels fine.”

1. Template: The draft follows the section structure in references/spec-template.md (or you note deliberate omissions and why). 2. No honor-system completeness: Steps 1–7 above are satisfied; unresolved placeholders/TODOs are confined to Open Questions (not smuggled into must-haves). 3. Leakage check: Every must-have / should-have passes the two-approach test under Implementation Leakage in references/spec-reviewer.md, except items explicitly listed under Constraints with rationale. 4. Artifact: The draft text exists in the conversation (or a single attached buffer) so the user is reviewing concrete prose, not a summary.

Writing the Spec

Pass before creating or overwriting `spec.md`: Do not write until both are true.

1. User gate: The user explicitly approved the draft or directed you to save/write the file (vague enthusiasm alone is not approval — confirm if unclear). 2. Path gate: Target path is finalized — default .beagle/concepts/<slug>/spec.md, slug resolved (from brief frontmatter or agreed headline).

• Default path: .beagle/concepts/<slug>/spec.md
• Slug source: inherit from brief.md frontmatter if a brief was ingested; otherwise derive a kebab-case slug from the concept headline (≤40 chars, no dates). User preferences override the default path.
• Companion outputs in-session: if brainstorm-beagle invokes web-research or artifact-analysis mid-session, pass output_dir: /abs/path/.beagle/concepts/<slug>/research/ or /abs/path/.beagle/concepts/<slug>/analysis/ so findings share the concept folder with anything PRFAQ produced upstream. This keeps the whole concept-forging audit trail in one place.
• Commit to git with message: docs: add <slug> project spec
• After writing, tell the user:

"Spec written to <path>. Review it and let me know if you want changes."

• Wait for approval before considering the brainstorm complete.

Key Principles

• One question at a time — don't overwhelm
• Follow the thread — don't walk a checklist
• YAGNI ruthlessly — remove anything that isn't clearly needed
• Concrete decisions only — "card-based layout" not "modern and clean"
• No implementation — WHAT and WHY, never HOW
• Capture everything — ideas outside scope go to Future Considerations, never lost
• Incremental validation — confirm understanding before moving on
• Every capability has a consumer — a must-have that introduces externally-facing surface names who/what consumes it, or it moves to Future Considerations; unconsumed surface is speculation
• The spec stands alone — anyone should be able to read it and understand the project

Spec Self-Review Checklist

Run this review after drafting the spec. Fix issues inline — don't flag them and move on.

Review Dimensions

1. Completeness

2. Consistency

3. Implementation Leakage

This is the most common failure mode. Scan every requirement for:

Exception: Constraints section may contain implementation-specific limits ("Must use PostgreSQL") when these are genuine external constraints with rationale.

The test: Could this requirement be satisfied by two completely different technical approaches? If yes, it's clean. If it implies exactly one approach, it's leaked.

4. Testability

Every requirement should pass the "how would you verify this?" test:

• Good: "User can undo the last action" — verify: perform action, press undo, confirm reversal
• Bad: "Intuitive undo support" — verify: ???

Rewrite any requirement where "verify" isn't obvious.

5. Atomicity

Each requirement should be one thing:

• Bad: "Users can search, filter, and sort results"
• Good: Three separate requirements — search, filter, sort

Compound requirements hide scope and make prioritization impossible.

6. Scope

Is this focused enough for a single planning cycle?

• More than 15 must-have requirements? Probably needs decomposition.
• Requirements spanning multiple independent subsystems? Decompose.
• Could you explain the core loop in 30 seconds? If not, it's too broad.

7. Reinvention (brownfield only)

For a feature being added to an existing codebase, the most expensive miss is specing a capability the code already has. The Prior Art Check step (in SKILL.md) should have run before drafting — this is the backstop.

If the prior art check was skipped, run it now: grep -riE '<capability synonyms>' across all source roots before approving. One matching file means a requirement needs reframing from "build X" to "extend/fix/wire-up the existing X."

8. Consumer (brownfield only)

A must-have that introduces new externally-facing surface with no named consumer is speculative — it can't be planned or verified.

If who/what consumes the surface isn't named, either name the consumer or move the item to Future Considerations before approving.

9. Composition (brownfield only)

For an existing mechanism the prior-art sweep surfaced that sits upstream or downstream in the same data pipeline, "the mechanism exists" is not the end — its composition with the new feature is the load-bearing question.

A new mechanism that composes wrongly with an existing one in the same pipeline ships broken even though neither piece was reinvented.

Calibration

Only fix issues that would cause real problems downstream.

A downstream planning system acting on this spec should be able to:

• Understand what to build without asking the user again
• Decompose requirements into tasks
• Know what's in scope and what's not
• Understand the constraints they're working within

Minor wording preferences, stylistic consistency, and "sections that could be more detailed" are not issues. Ambiguity that could lead someone to build the wrong thing IS an issue.

Approve the spec unless there are serious gaps. Then present to the user for review.

Spec Document Template

Use this template when writing the final spec document. Save to docs/specs/YYYY-MM-DD-<topic>.md.

Template

# [Project Name]

**Created:** [YYYY-MM-DD]
**Status:** Ready for planning

## Core Value

[ONE sentence — the single most important thing this project delivers. If everything else fails, this must work. Drives prioritization when tradeoffs arise.]

## Problem Statement

[What problem exists, who has it, and why it matters now. 2-4 sentences. Include what people do today without this (the status quo) and why that's insufficient.]

## Requirements

### Must Have

[Concrete, testable, user-centric. These define v1 — the project isn't done without them.]

- [Requirement — observable, verifiable outcome]
- [Requirement — observable, verifiable outcome]

### Should Have

[Important but not blocking v1. Build these if time allows, defer if not.]

- [Requirement — observable, verifiable outcome]

### Out of Scope

[Explicit exclusions with reasoning. Prevents scope creep and re-litigation.]

- [Exclusion] — [why not]
- [Exclusion] — [why not]

## Constraints

[Hard limits on the solution space. Each must include WHY — constraints without rationale get questioned.]

- **[Type]:** [What] — [Why]
- **[Type]:** [What] — [Why]

Common types: Tech stack, Timeline, Compatibility, Performance, Security, Regulatory, Team

## Key Decisions

[Significant choices made during brainstorming. Captures the reasoning so downstream work doesn't relitigate.]

### [Decision Area]
- **Decision:** [What was decided]
- **Alternatives considered:** [What else was on the table]
- **Rationale:** [Why this choice]

### [Decision Area]
- **Decision:** [What was decided]
- **Alternatives considered:** [What else was on the table]
- **Rationale:** [Why this choice]

## Reference Points

[Inspiration, external docs, "I want it like X" moments, specific behaviors or patterns the user referenced. Not implementation instructions — direction and taste.]

[If none: "No specific references — open to standard approaches."]

## Open Questions

[Unresolved items that need research or future discussion before or during implementation. Flag what's unknown so downstream systems can investigate.]

- [Question — what needs to be figured out and why it matters]

[If none: "No open questions — spec is self-contained."]

## Future Considerations

[Ideas that emerged during brainstorming but belong in later phases or separate projects. Captured so they're not lost, explicitly deferred.]

[If none: "None — brainstorming stayed within scope."]

Guidelines

Core Value:

• Rarely more than one sentence
• Not a tagline — a prioritization tool
• Should resolve ambiguity when two requirements compete

Requirements — quality checklist:

• Can someone verify this was met? (testable)
• Does it describe what the user experiences? (user-centric)
• Is it one thing, not a bundle? (atomic)
• Could it be interpreted two ways? If so, pick one.

Requirements — what NOT to write:

• Implementation tasks disguised as requirements ("Create a REST API")
• Vague qualities ("Good performance", "Modern UI")
• Compound requirements ("Users can search AND filter AND sort")
• Technical jargon the user didn't use

Constraints vs Key Decisions:

• Constraint: imposed externally, limits the solution space ("Must run on iOS 16+")
• Key Decision: chosen during brainstorming, shapes the direction ("Mobile-first, desktop secondary")

Key Decisions — when to record:

• When 2+ viable options existed and one was chosen
• When the user expressed a strong preference
• When a direction was explicitly rejected (alternatives section)
• When the user said "you decide" — record it as "the agent's discretion" with the area

Reference Points — good content:

• "I want the search to feel like Spotlight — instant, forgiving of typos"
• "The onboarding should be like Linear's — minimal, progressive, no tutorial walls"
• External docs the user wants to be followed: path/to/spec.md with what it covers

Future Considerations — the redirect: When an idea is captured here during brainstorming, it was explicitly deferred. Note what it is and why it's deferred (too complex for v1, depends on other work, nice-to-have, etc.).

Examples

Example 1: Developer Tool

# Logwatch — Spec

**Created:** 2026-03-26
**Status:** Ready for planning

## Core Value

Developers see exactly what happened in production without leaving their terminal.

## Problem Statement

When a production incident occurs, developers switch between Grafana, CloudWatch, and Slack to piece together what happened. This context-switching wastes 10-15 minutes per incident and often means important log lines are missed. Logwatch brings structured log tailing and search into the terminal where developers already work.

## Requirements

### Must Have

- User can tail logs from multiple services simultaneously in a split-pane view
- User can search logs by time range, service name, and log level
- User can bookmark a log line and return to it later in the same session
- Log output is syntax-highlighted by log level (error=red, warn=yellow, info=default)
- User can filter to a single service from the multi-service view without losing scroll position
- Connection drops are detected within 5 seconds and auto-reconnected

### Should Have

- User can save a search query and replay it in a future session
- User can export a time range of logs to a file
- User can share a permalink to a specific log line with teammates

### Out of Scope

- Alerting or notification — this is a viewing tool, not a monitoring tool
- Log aggregation or storage — reads from existing infrastructure
- Dashboard creation — Grafana already handles this well
- Mobile support — terminal-first, desktop only

## Constraints

- **Compatibility:** Must work with CloudWatch Logs and Datadog — these are our two log backends
- **Performance:** Must handle 10k log lines/second without dropping frames
- **Distribution:** Single binary, no runtime dependencies — devs install via brew or curl
- **Auth:** Must support SSO via existing Okta setup — no separate credentials

## Key Decisions

### Primary interface
- **Decision:** TUI with vim-style keybindings
- **Alternatives considered:** Web UI, VS Code extension, plain CLI with flags
- **Rationale:** Developers are already in the terminal during incidents. TUI keeps them in flow. Vim bindings match muscle memory for the team.

### Multi-service display
- **Decision:** Vertical split panes, one per service, synchronized by timestamp
- **Alternatives considered:** Interleaved single stream with service prefixes, tabbed view per service
- **Rationale:** Side-by-side makes cross-service correlation visual and immediate. Interleaved gets noisy above 3 services. Tabs hide context.

## Reference Points

- "I want it to feel like `lazygit` — fast, keyboard-driven, just works"
- "The search should be like ripgrep — regex by default, fast enough to feel instant"
- Okta SSO integration spec: `docs/infra/sso-integration.md` (sections 2-3 cover token flow)

## Open Questions

- Can we get sub-second latency from CloudWatch's API, or do we need a local cache layer? Needs benchmarking.
- Datadog's log query API has rate limits — need to verify they're sufficient for real-time tailing.

## Future Considerations

- Alerting integration (pipe to PagerDuty) — separate project, depends on core being stable
- Log annotation ("this line caused the outage") — great idea, v2 feature
- Team sharing of saved queries — requires backend, save for later

Example 2: Minimal Project

# Markdown Link Checker — Spec

**Created:** 2026-03-26
**Status:** Ready for planning

## Core Value

Broken links in docs are caught before they reach readers.

## Problem Statement

Our documentation has 200+ external links. We discover broken links when users report them, sometimes weeks after the target page moved. An automated checker in CI catches these before merge.

## Requirements

### Must Have

- Scans all `.md` files in a directory recursively
- Checks HTTP status of external links (follows redirects up to 3 hops)
- Reports broken links with file path, line number, URL, and HTTP status
- Exit code 1 if any links are broken (for CI gating)
- Completes scan of 200 files with 500 links in under 60 seconds

### Should Have

- User can exclude URLs by pattern (regex allowlist)
- User can set a custom timeout per link

### Out of Scope

- Checking anchor fragments (#section-name) — parsing target HTML is too complex for v1
- Fixing broken links — detection only
- Checking internal cross-file links — separate concern

## Constraints

- **CI:** Must run in GitHub Actions — no external service dependencies
- **Language:** Team prefers Go for CLI tools — aligns with existing tooling

## Key Decisions

### Concurrency model
- **Decision:** Concurrent link checking with configurable parallelism
- **Alternatives considered:** Sequential checking (simple but slow), unbounded parallelism (risks rate limiting)
- **Rationale:** Need to finish in 60s but also avoid hammering external servers. Default 10 concurrent, configurable via flag.

## Reference Points

- "Like `markdown-link-check` npm package but faster and no Node dependency"

## Open Questions

- Should rate-limited responses (429) be treated as broken or retried? Need to decide retry policy.

## Future Considerations

- Anchor fragment checking — worth a follow-up if teams request it
- Cache layer for recently-checked URLs — would speed up repeated CI runs