How to Write Bolt Specs

Bolts are the atomic unit of construction in the DLC. Each bolt is a well-scoped piece of work with clear acceptance criteria, mapped to specific ARC constraints.

Prerequisites

• An ARC must exist in _cat/artifacts/architecture/
• A Feature list should exist (from cat-features-create)
• Readiness Check should pass (recommended)

Creating Bolt Specs

cat-bolt-writer

Julian decomposes a Feature into Bolts. For each bolt, Julian defines:

1. Scope — What exactly this bolt builds
2. ARC Constraint Mapping — Which ARC constraints this bolt must satisfy
3. Acceptance Criteria — Specific, testable criteria for “done”
4. Testing Requirements — What tests must pass
5. Dependencies — What must exist before this bolt can execute

Example Bolt Spec

# Bolt 1.1: POST /api/password-reset endpoint

## Scope
Create the password reset request endpoint that accepts an email address
and initiates the reset flow.

## ARC Constraints
- MUST-001: Rate-limit to 3 requests per hour per email
- MUST-003: Return 200 OK regardless of email existence
- MUST-NOT-001: Must not reveal whether email exists in system

## Acceptance Criteria
- [ ] Endpoint accepts POST with JSON body { "email": "..." }
- [ ] Returns 200 OK for all valid email formats
- [ ] Rate limiting enforced at 3/hour/email
- [ ] Invalid email format returns 400
- [ ] Fires async event for token generation

## Testing
- Unit tests for input validation
- Integration test for rate limiting
- Security test for email enumeration prevention

Output: _cat/artifacts/construction/bolt-spec-{bolt_id}.md

How Many Bolts Per Feature?

Feature Size	Typical Bolts	Example
Small	1–2	Config change, simple endpoint
Medium	3–5	New API with multiple endpoints
Large	5–8	New service or major subsystem

If a feature needs more than 8 bolts, consider splitting it into sub-features first.

Editing Bolt Specs

cat-bolt-edit

Julian reads an existing bolt spec and helps you modify it in-place.

Bolt Spec Best Practices

1. One responsibility per bolt. If you find yourself saying “and also,” it’s probably two bolts.

2. Acceptance criteria should be testable. Each criterion should map to at least one test case.

3. Map every ARC constraint that applies. During bolt execution, Marcus checks each mapped constraint. Missing mappings mean unchecked constraints.

4. Order bolts by dependency. Bolt 1.1 (endpoint) before Bolt 1.2 (email dispatch) — the dispatch needs the endpoint to exist.

---

See Also: What Are Bolts? · Execute Bolts · Construction Phase