0fea499957
Every document filename now mirrors its lifecycle state with a status suffix (e.g., .draft.md, .wip.md, .accepted.md). No more bare .md for tracked document types. Also renamed all from_str methods to parse to avoid FromStr trait confusion, introduced StagingDeploymentParams struct, and fixed all 19 clippy warnings across the codebase. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1.8 KiB
1.8 KiB
RFC 0001: Efficient Document Format
| Status | Draft |
| Date | 2026-01-23 |
Summary
Define a more efficient document format for Blue's ADRs, RFCs, and other documents that balances human readability with machine parseability.
Problem
The current document format uses verbose markdown tables and prose. While readable, this creates:
- Redundant boilerplate in every document
- Inconsistent structure across document types
- More parsing overhead for tooling
Proposal
Consider one of these approaches:
Option A: YAML Frontmatter + Minimal Body
---
title: Purpose
status: accepted
date: 2026-01-20
type: adr
number: 1
---
## Context
Right then. First things first...
## Decision
**Blue exists to make work meaningful and workers present.**
## Consequences
- Tools should feel like invitations, not mandates
Option B: Structured Markdown Sections
Keep pure markdown but enforce consistent section headers that can be reliably parsed:
# ADR 0001: Purpose
**Status:** Accepted
**Date:** 2026-01-20
## Context
...
## Decision
...
## Consequences
...
Option C: Single-File Database
Store metadata in SQLite/JSON, keep only prose in markdown files. Tooling reads metadata from DB, content from files.
Goals
- Reduce boilerplate per document
- Enable reliable machine parsing
- Maintain human readability
- Keep Blue's voice in prose sections
Non-Goals
- Complete rewrite of existing docs (migration should be automated)
- Binary formats
Open Questions
- Which option best balances efficiency with readability?
- Should we support multiple formats during transition?
- How do we handle the existing 13 ADRs?
"Keep it simple. Keep it readable. Keep it yours."
— Blue