Core Workflow
The practical Cuddler sequence: define the domain, validate the data, validate the template document, and render only after both pass.
The core Cuddler sequence
The order matters because each step reduces ambiguity before the next one begins.
Start from the Specification Root and the right Document Role.
Use the shared Artifact Specification to frame how the artifact family should be authored.
Shape the data JSON and markdown-template JSON for the same version family.
Validate the data first and the markdown template document second.
Only render once the contracts are sound and aligned.
If a step fails, go back to that boundary instead of trying to push the workflow forward.
The Cuddler workflow is intentionally staged. Each step reduces ambiguity before the next one begins, which makes the final rendered output easier to trust and easier to review.
The sequence
- Start with the governing Specification Root and the relevant Document Role , because the role complies with that root.
- Use the shared Artifact Specification alongside the chosen Document Role to understand how the target Artifact Definition should be authored.
- Shape the data JSON and the markdown-compliant template JSON so they stay aligned with the intended schema version.
- Validate the data first, then validate the template document against the template schema.
- Render only after both validations succeed.
What to keep in mind
- Data validation and template validation solve different problems.
- A versioned contract is easier to reason about than an implied one.
- If validation fails, the issue should be fixed before rendering is attempted again.
Why the order matters
The order protects the document pipeline from hidden drift. When the data is validated first, the template document is working against a known source shape. When the template document is validated second, it is checked independently instead of borrowing confidence from the data.
