Fable Artifact

Turn requirements and evidence into a standalone artifact whose content, structure, diagrams, links, and rendered output can all be checked independently.

Mission

An artifact is not successful because the Markdown parses or the diagram looks polished. It must communicate the right claims to the right audience, preserve source truth, make assumptions visible, and render in the medium the user will actually consume.

Activate When

• producing RFCs, architecture proposals, technical reports, runbooks, decision records, diagrams, or rich standalone documentation;
• packaging analysis/results into a durable document;
• creating a diagram or interactive explanatory artifact from established requirements/evidence.

Do Not Activate When

• a one-paragraph answer is sufficient;
• application logic itself needs modification (fable-execute);
• the main work is numerical chart selection (fable-dataviz);
• facts required by the artifact have not been researched/discovered yet.

Artifact Classification

Protocol

Stage 1 — Define audience and job

State who will use the artifact and what decision/action it must support. One artifact can contain multiple sections, but it should have one primary communication job.

Stage 2 — Build a claim/source map

Before writing polished prose, identify:

• measured/source-backed facts;
• design decisions;
• assumptions/inferences;
• unresolved items;
• data/visual sources;
• claims that need citations/links.

Do not invent examples, metrics, architecture components, test results, or citations to make the document feel complete.

Stage 3 — Choose structure from artifact type

Examples:

• RFC: context → goals/non-goals → evidence → options → decision → design → risks → rollout/rollback → acceptance;
• runbook: symptom/trigger → safety prerequisites → diagnosis → action → verification → rollback/escalation;
• architecture: scope → context → components/boundaries → flows → data/state → failure/security → deployment/operations → decisions.

Avoid generic template sections that do not serve the document's job.

Stage 4 — Design diagrams semantically

Each node/edge should represent a real component, state, dependency, event, or data/control flow. Label direction/meaning where ambiguity exists.

For Mermaid or other text diagrams:

• validate syntax;
• quote/escape labels safely;
• avoid giant unreadable graphs;
• split views by question (context, container, sequence, state) when one diagram becomes overloaded.

Stage 5 — Write for scanning and decision quality

Use hierarchy, short sections, tables only when comparison benefits, callouts sparingly, and explicit Decision, Risk, Unknown, Evidence language where useful.

Do not turn every sentence into bullets or bury the main decision below background detail.

Stage 6 — Validate internal consistency

Cross-check:

• terms/names/versions match throughout;
• diagram matches prose;
• examples match actual API/schema;
• links/anchors exist;
• recommendations follow cited evidence;
• no section contradicts the accepted design.

Stage 7 — Render in the target medium

A source file is not the final artifact when rendering matters. Preview/render Markdown/Mermaid/HTML/PDF/other target as appropriate and inspect for clipping, broken diagrams, overflow, missing assets, unreadable typography, or inaccessible interactions.

Stage 8 — Run truth and usability review

Ask:

• can the audience locate the primary decision/action quickly?
• which statements are fact vs proposal vs inference?
• are any claims unsupported?
• would a diagram imply a relationship that does not exist?
• can a future reader execute/maintain the artifact without chat context?

Decision Rules

• Prefer explicit unknown/not checked to filling gaps with plausible content.
• A diagram should answer a question; split it when one view mixes topology, sequence, deployment, and ownership beyond readability.
• Use links/citations for external/current claims where traceability matters; do not fabricate sources.
• Generated charts/tables inherit their data provenance from DataViz/research packets.
• If artifact changes as the design changes, reconcile every diagram/example/decision reference before completion.
• Interactive artifacts need keyboard/accessibility/fallback behavior appropriate to their use; visual novelty is not a substitute for communication.
• Keep implementation details out of an executive/decision artifact unless they materially change the decision.
• Use the repository/designated artifact destination; do not litter roots/temp paths.

Invariants

• Every factual claim is source-backed or clearly labeled as inference/proposal.
• No fake data, citations, test results, architecture components, or case studies.
• Diagram/prose/examples describe the same design.
• Target rendering is checked when rendering is part of delivery.
• Artifact stands alone without requiring hidden conversation context.
• Audience can identify the primary decision/action.

Failure Taxonomy

Content hallucination

Missing fact is filled with plausible detail. Remove/research/label unknown.

Diagram semantic drift

Diagram no longer matches current design or implies false flow. Regenerate/reconcile.

Template bloat

Generic sections obscure the document's job. Remove sections without decision value.

Source/render mismatch

Markdown/HTML code looks valid but target renderer clips/breaks assets/diagram. Verify rendered output.

Internal contradiction

Versions/names/decisions differ across sections. Establish one canonical claim map and reconcile.

Audience mismatch

Document is technically complete but too low/high altitude for intended reader. Reorganize around their decision/action.

Link/source rot

Critical evidence points to invalid/missing paths. Repair or preserve relevant content locally when appropriate.

Anti-Patterns

• fake metrics to make proposal persuasive;
• Mermaid diagram full of decorative boxes with no clear edge semantics;
• generic "Overview / Architecture / Conclusion" template regardless of job;
• copying raw research notes without synthesis;
• using callout blocks everywhere;
• claiming rendered/accessible without previewing target medium;
• architecture prose updated while diagram remains stale;
• citations that do not support the sentence;
• giant wall of implementation detail before the main decision.

Artifact Packet

Audience / job:
Artifact type + destination:
Claim/source map:
Decisions vs assumptions vs unknowns:
Structure rationale:
Diagram(s) + question answered:
Data/source provenance:
Internal consistency checks:
Rendered validation:
Accessibility/usability check:
Known limitations:

Completion Criteria

Artifact completes when:

• content is evidence-grounded and audience/job-aligned;
• structure supports the intended decision/action;
• diagrams/examples/data are semantically consistent;
• unknowns are explicit rather than invented;
• target rendering/links/assets are validated;
• a zero-context reader can understand and use the artifact.

Progressive Resources

• Deep guide: references/source-grounded-artifact-design.md
• Existing guide: references/artifact-composition-guide.md
• Example: examples/system-architecture-diagram.md