Skip to content

Commit bcd16ac

Browse files
ssomayyajulaclaude
andcommitted
[doc] Executive summary: compare with existing doc PRs (strata-org#1136, strata-org#1144)
Add section explaining why existing documentation efforts (PRs strata-org#1136 and strata-org#1144) are complementary but insufficient: they document WHAT the pipeline does but don't specify WHEN coercions fire, WHAT constitutes valid intermediate output, or HOW to arbitrate design disagreements. Positions both efforts as valuable (document as-is) while distinguishing the architecture spec (document should-be, precise enough for mechanical implementation). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent edfb827 commit bcd16ac

1 file changed

Lines changed: 33 additions & 0 deletions

File tree

docs/refactor/EXECUTIVE_SUMMARY.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,39 @@ one typing rule to Elaboration. Both can be verified independently.
134134

135135
---
136136

137+
## Why Existing Documentation Efforts Are Insufficient
138+
139+
PRs #1136 ("Document the Python front-end") and #1144 ("Document the design of
140+
Laurel") are open and add valuable narrative documentation. They describe WHAT the
141+
pipeline does: the stages, data structures, naming conventions, supported constructs,
142+
and general design rationale.
143+
144+
However, they do not provide the kind of specification that would have prevented
145+
the problems above. Specifically, they do not specify:
146+
147+
- **When coercions fire.** PR #1136 documents the Any-boxing encoding (constructors
148+
like `from_int`, destructors like `Any..as_int!`) but does not specify the rule
149+
for when Translation should insert them. A contributor reading the doc still
150+
cannot determine whether a given expression needs wrapping without studying the
151+
existing code.
152+
153+
- **What constitutes valid intermediate output.** Neither doc specifies structural
154+
invariants that each pass's output must satisfy. Without these, pass-ordering
155+
bugs (PR #1011) remain possible — a pass can produce "valid Laurel" that the
156+
next pass cannot handle.
157+
158+
- **How to arbitrate design disagreements.** PR #954's 100+ comment thread exists
159+
because both approaches are consistent with a WHAT-level description. A
160+
specification that determines calling conventions from grades would resolve it:
161+
the grade lattice computes which approach is correct.
162+
163+
The existing documentation efforts are complementary to this refactor — they
164+
document the system as it is. The architecture specification documents what the
165+
system SHOULD be, with enough precision that implementation is mechanical and
166+
disagreements are resolvable by reference to the spec.
167+
168+
---
169+
137170
## The New Architecture
138171

139172
The replacement pipeline is governed by a formal specification

0 commit comments

Comments
 (0)