Iso 24495 3 by @gazmagik · Skillet

Iso 24495 3 by @gazmagik · Skillet

Progressive Disclosure Ordering: Structure every technical explanation in these stages, in this order:
1. System Purpose: High-level operational intent (1 sentence).
2. Architecture & Data Flow: Diagram (Mermaid) or summary table. Rule 4 governs the diagram's text alternative, and Part 5 governs the table. Required where the explanation covers how more than one component relates to another. A single mechanism needs none, and neither does a sequence of steps that an ordered list already presents in order. A diagram nobody needs is the decoration Part 5 forbids.
3. Implementation Detail: Concrete code snippet with exact file citations.
These stages order an explanation, and Part 5's three levels order a document. They are different axes rather than two versions of one, so they do not map one to one. Where the explanation is a document:
- The purpose sentence supplies the purpose line of Part 5's opening block, and opens its overview where Part 5 calls for one. The block's title, version and named reader are not its to supply, and Part 5 still requires them of the author. That overview also keeps the conclusion, the action required and any essential qualification, which one sentence does not.
- Stages 2 and 3 sit in the main body, in that order.
- Part 5's optional detail holds what a reader can skip and still act on. No stage covers it, so nothing is demoted there by default.
A stage covers what the explanation contains. A runbook explains what to do and a decision record explains a choice, so neither needs stage 2's diagram of components nor stage 3's code. Omit a stage the explanation has no content for, and keep the order of those it has. They also do not exclude what a genre needs beside them: an incident report's timeline sits with the stages rather than inside one.
File & Code Citation Standard:
- Quote exact file locations using markdown links with line numbers: [filename](file:///path/to/file#L10-L20).
- Never describe code changes or logic without citing the exact file and line range. This governs an explanation of code. A guide describing what a user does needs no citation.
Terminology & Acronym Standardisation:
- Define every acronym or domain-specific term upon first use in parentheses (e.g. "Abstract Syntax Tree (AST)").
- Use consistent symbol names across text, code snippets, and diagrams.
Diagrams and Their Alternatives:
- Give every diagram a text alternative saying what it shows, not what it is. Part 5 requires that of any image carrying meaning. Stage 2 above offers a diagram as one way to meet it, so this rule says where the alternative goes. A summary table is the other way, and Part 5 already governs it.
- A Mermaid diagram reaches a listener as its source text, which is not an explanation. So the alternative is prose beside the diagram, never the diagram's own labels.

❌ Not aligned (Dense & Abstract):

In order to prevent race conditions during concurrent state mutations
within the execution pipeline, a mutex lock mechanism is introduced prior
to updating the shared buffer allocation in memory.

✅ ISO 24495-3 Aligned:
System Purpose: Acquire a Mutex Lock to prevent data corruption during concurrent writes.

Implementation Detail: The locking logic is implemented in state_manager.rs:L45-L52:
```
let _guard = self.mutex.lock().unwrap();
self.buffer.update(data);
```