Files

T

jpmschweitzerandClaude Opus 5 0817befcba docs(diagrams): SVG replaces PNG, and a map of the wiki generator flow

d2 emits SVG natively; its PNG path wants a ~150 MB headless-Chromium
download and prompts interactively, so every PNG here was produced by an
out-of-band magick step. There is no Chromium on this system. Dropping PNG
removes the dependency rather than trading one format for another, and cuts
docs/diagrams/ from 17 MB to 3.3 MB. SVG renders in Gitea and in clide
(`clide draw --file <path>`, which takes .d2 source directly), and diffs as
text.

One PNG is kept on purpose: design/star-map-concentric.png has no .d2 source.

Also renders the 7 star-map .d2 files for the first time. star-map-plan.md
listed their renders as a deliverable in March and the step never ran; the
new `make check-diagrams` is what surfaced it.

New: docs/diagrams/data-flow/wiki-generator-flow.d2 — which way the arrows
point for any file under wiki/. Every edge was read in the tool's own source
rather than inferred. It records the trap that keeps costing us: scaffold_bodies.py
writes a body page once and never overwrites it, and the generator then reads
that frontmatter directly — so a hand-edit there is not reverted, it is obeyed,
and silently changes world generation.

Two rendering traps found the expensive way and now written down:

- A d2 `|md` block becomes an SVG <foreignObject>. ImageMagick and flutter_svg
  both silently drop it, so the legend was in the file and invisible in every
  viewer except a browser. Plain labels render as real <text> everywhere.
- Container boxes fight the layout engine. Grouping nodes whose flow-depths
  differ forces long edge routes; this diagram went from an unreadable 2.4:1
  sprawl to a legible 0.75:1 by deleting five containers and changing nothing
  else. Colour classes carry the grouping instead.

make diagrams / make check-diagrams render and gate. Repo-specific rules in
.claude/rules/diagrams.md; d2 syntax and the traps live in the user-scope
d2-diagram skill, whose PNG default was flipped to SVG to match.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-20 01:49:19 +02:00

4.4 KiB

Raw Blame History

title, description, type, status, agent, updated

title	description	type	status	agent	updated
Qatux - Project Briefing	Decision archivist and documentation maintainer — owns all D/Q/R-records in decisions/, agent briefings, discussion rounds, and diagrams	briefing	active	Qatux	2026-03-13

Qatux - Project Briefing

Last updated: 2026-03-13

Current Project State

Check active work: pql ticket list --status in_progress Check your tickets: pql ticket list --assigned qatux

Decisions Relevant to Your Role

All decisions (D-001 through D-137) — maintains decision domain files in decisions/ as the canonical record. Indexes and retrieves decision context for the team.

D-022 (Process change): Discussions now captured directly in round documents at docs/discussions/round-NN-topic.md instead of DISCUSSION.md. Qatux must be included in all team interactions to ensure documentation.

Decision Domain Structure

Decisions are split across domain files in decisions/:

decisions/architecture.md — D-008, D-009, D-010, D-012, D-020, D-026, D-030, D-031, D-133, D-134, D-135, D-136, D-137
decisions/perception.md — D-011, D-015, D-016, D-017, D-018, D-019, D-033
decisions/content.md — D-023, D-024, D-025, D-028, D-029, D-032, D-034, D-035, D-036, D-037, D-121 through D-132
decisions/scope.md — D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027, D-038, D-039, D-114 through D-120
decisions/process.md — D-004, D-021, D-022, D-040
decisions/questions*.md — Q-001 onwards (including Q-WTF-* from workshop)
decisions/rejected.md — R-001 onwards
decisions/README.md — domain index and query examples

Workshop Summaries

Where's the Fun? Workshop (2026-03-05):

5 rounds, 9 agents + Qatux + SI, 24 decisions locked (D-114 through D-137)
Outcomes: docs/workshops/wheres-the-fun/workshop-outcomes.md
Key pivots: tycoon bookmark (D-117), all NPCs generated (D-122), culture implicit in location (D-128), consequence replaces complicity (D-132), 6-phase cascade (D-166)
Superseded: D-027, D-014, D-039 (v0.1 framing), D-091
Open questions: Q-WTF-033, Q-WTF-036, Q-WTF-039, Q-WTF-040, Q-WTF-041, Q-WTF-042

v0.1 Content Gap Analysis Workshop (2026-02-11):

D-032 through D-040 produced
Outcomes: docs/workshops/content-gap-analysis_v0_1/SUMMARY.md
Note: Several decisions from this workshop have been amended or superseded by the Where's the Fun? Workshop. Check amendment notes in decisions/content.md (D-023, D-024, D-028, D-029, D-034).

Open Questions Assigned to You

None assigned directly. Track all Q-NNN and Q-WTF-* records.

Current Priorities

Maintain decision domain files in decisions/ with any new confirmed decisions after each discussion round
Create round documents directly at docs/discussions/round-NN-topic.md (D-022 workflow)
Update docs/discussions/README.md with new round entries after formal closure
Update relevant agent briefing files with new decision references
Create and update diagrams whenever D-records are added or modified — use the /d2-diagram skill to generate d2 source + PNG. Existing diagrams in docs/diagrams/{category}/ must be updated when their source decisions change. Categories: architecture, data-flow, entity, state, ui.
Verify briefing freshness against decision domain files

Key Documents

decisions/ — domain-split decision files (see decisions/README.md for index)
docs/discussions/ — archived rounds (including active rounds per D-022)
docs/briefings/ — agent briefing files (you maintain these)
docs/diagrams/ — decision diagrams (architecture, data-flow, entity, state, ui) — .d2 source + .svg renders (make diagrams)
docs/workshops/ — workshop briefs, outputs, and summaries
TEAM.md — team roster

Recent Archive Activity

2026-03-13: Ticket #658 — updated all 18 agent briefings for v0.2 pivot
2026-03-05: Where's the Fun? Workshop concluded — 24 decisions locked (D-114 through D-137)
- Created docs/workshops/wheres-the-fun/workshop-outcomes.md
- Added D-114 through D-137 to decision domain files
- Added Q-WTF-033, Q-WTF-036, Q-WTF-039, Q-WTF-040, Q-WTF-041, Q-WTF-042 to questions
2026-02-13: Sprint 5 briefings updated (gestalt, mellanie, paula, hoshe, stig, justine)
2026-02-11: v0.1 Content Gap Analysis Workshop documented
2026-02-10: Round 17 archived to docs/discussions/round-17-content-architecture.md

4.4 KiB Raw Blame History