superviber/blue
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
blue/.blue/docs/spikes/2026-01-26T1100Z-consistent-table-headers-in-generated-docs.wip.md
Eric Garcia 0fea499957 feat: lifecycle suffixes for all document states + resolve all clippy warnings 
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>
2026-01-26 12:19:46 -05:00

3.1 KiB
Raw Blame History

Spike: Consistent Table Headers In Generated Docs
Status In Progress
Date 2026-01-26
Time Box 1 hour

Question

How can we ensure all Blue-generated documents use consistent table header formatting? Currently two patterns exist: (1) headerless metadata tables | | |\n|---|---| used by most doc types, and (2) inline bold metadata like **Date**: value used by Decision and Alignment Dialogue. We need to catalog all inconsistencies, decide on a single standard, and identify the code changes needed.

Findings

Current State: 10 Document Types, 3 Metadata Patterns

Pattern A — Headerless metadata table (the standard):

| | |
|---|---|
| **Status** | Draft |
| **Date** | 2026-01-26 |

Used by: RFC, Spike, ADR, Audit, Postmortem, Runbook, PRD, Dialogue — 8 of 10 types.

Pattern B — Inline bold with colon:

**Date:** 2026-01-26

Used by: Decision only (crates/blue-core/src/documents.rs:413).

Pattern C — Inline bold with colon (multiline):

**Draft**: Dialogue 0001
**Date**: 2026-01-26 14:30
**Status**: In Progress
**Participants**: 💙 Judge, 🧁 Croissant, 🧁 Brioche

Used by: Alignment Dialogue only (crates/blue-mcp/src/handlers/dialogue.rs:781-794).

Named-Column Data Tables (Already Consistent)

All data tables across doc types use proper column headers with separator rows. No inconsistency here:

Document Table Columns
Postmortem Timeline Time, Event
Postmortem Action Items Item, Owner, Due, Status, RFC
Runbook Escalation Level, Contact, When
Dialogue Rounds Round, Topic, Outcome
Alignment Expert Panel Agent, Role, Emoji
Alignment Scoreboard Agent, Wisdom, Consistency, Truth, Relationships, Total
Alignment Perspectives ID, Agent, Perspective, Round
Alignment Tensions ID, Tension, Status, Raised, Resolved
PRD Success Metrics Metric, Current, Target

Files Requiring Changes

Only 2 functions need updating:

  1. crates/blue-core/src/documents.rs — Decision::to_markdown() (line 413)

    • Change: **Date:** {} inline format → headerless metadata table
    • Add | | |\n|---|---| block with Date row

  2. crates/blue-mcp/src/handlers/dialogue.rs — generate_alignment_dialogue_markdown() (lines 781-794)

    • Change: inline bold metadata block → headerless metadata table
    • Move Draft, Date, Status, Participants, RFC into table rows

Validation Approach

The codebase already has validate_rfc_header() and convert_inline_to_table_header() in documents.rs (lines 585-688) that detect and convert inline headers to table format. These could be extended as a lint/migration tool for existing docs, but the primary fix is in the generation code itself.

Recommendation

Standardize on Pattern A (headerless metadata table | | |\n|---|---|) for all document metadata. This is a 2-file, ~20-line change. Named-column data tables are already consistent and need no changes.

Investigation notes by Blue