A Narrative Block is a free-form Markdown section attached to an Initiative PRD. While most Initiative content is structured — Requirements, Change Proposals, Tasks, Risks — some context defies structured fields: design principles that constrain all decisions, an architecture diagram with explanatory prose, a glossary of terms specific to this engagement, or compliance constraints that span the entire scope.
Narrative Blocks fill this gap. They live alongside the structured content in the PRD view and can be ordered to appear wherever the narrative flow demands.
Block Types
Each Narrative Block has a block_type that communicates its purpose:
| Type | When to Use |
|---|---|
| design_principles | Core design philosophy and guiding principles for the Initiative |
| architecture | Architecture decisions, patterns, and technical approach |
| glossary | Domain-specific term definitions that apply across the Initiative |
| security | Security requirements, threat model, or compliance constraints |
| constraints | Technical, business, or regulatory limits on the solution space |
| custom | Free-form sections for anything that doesn’t fit the above (default) |
Block type is a label for human orientation, not a behavioral constraint. All block types behave identically; the type simply communicates what kind of content a reader should expect.
Content Format
The content field stores raw Markdown. Catalio renders it to HTML using MDEx at display time. Use standard Markdown: headings, lists, tables, bold/italic, and fenced code blocks all work. Emoji and extended syntax are supported.
Ordering
Blocks within an Initiative are ordered by position (ascending). When you create a block without specifying a position, it is automatically assigned a position one greater than the current maximum — it appears last. To reorder, update the position values directly (the AI assistant can do this for you).
Key Fields
| Field | Purpose |
|---|---|
| title | Block heading displayed in the PRD (e.g., “Design Principles”, “Glossary”) |
| content | Markdown body of the narrative section |
| block_type | Semantic category of the block (see Block Types above) |
| position | Display ordering within the initiative (lower numbers appear first) |
Narrative Blocks vs. Structured Content
Narrative Blocks and structured resources serve different purposes and are not interchangeable:
| Structured Resources | Narrative Blocks |
|---|---|
| Requirements, Risks, Tasks — each with defined fields | Free-form prose and structured Markdown |
| Machine-readable: filterable, queryable, reportable | Human-readable: context and explanation |
| Individual records with lifecycle (status, owner) | Sections in a document with no lifecycle |
| Used by AI tools for analysis and proposals | Read by humans; not directly processed by AI tools |
Use structured resources for things Catalio needs to reason about. Use Narrative Blocks for things people need to understand.
Best Practices
One purpose per block.
A block titled “Design Principles, Architecture, and Constraints” is three blocks compressed into one. Split it — readers and editors will find the content faster, and the AI assistant can navigate it more accurately.
Write for a new team member.
The most useful Narrative Blocks assume the reader knows nothing about the specific engagement. “We chose a microservices approach” is unhelpful. “We chose a microservices approach because the legacy monolith cannot be incrementally deployed, and the business requires zero-downtime releases during the 18-month migration window” gives the reader everything they need.
Use the Glossary type for domain terms.
Every legacy modernization engagement has its own vocabulary — acronyms, system names, and business terms that mean something specific in this context. A Glossary block prevents miscommunication across teams. Create it early and update it as new terms emerge.
Keep Design Principles actionable.
“Be user-friendly” is not a design principle — it provides no guidance when facing a real trade-off. “Prioritize task completion over feature richness: when choosing between a power-user feature and a simplified default workflow, choose the default workflow” is actionable. It tells the team what to choose when they hit a constraint.
Let position reflect the narrative arc.
The PRD tells a story. Design Principles and Constraints belong near the top (they frame everything that follows). Architecture decisions belong after scope but before implementation tasks. Glossary typically belongs at the end as a reference. Use position to make the PRD readable in order.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Initiative | Narrative Blocks belong to an Initiative |
| Requirements | Requirements provide the structured content; Narrative Blocks provide the context |
| Change Proposals | Change Proposals track requirement changes; Narrative Blocks document decisions |
Next Steps
- Understand Initiatives — Learn the full PRD structure Narrative Blocks enrich
- Work with Requirements — See how structured requirements complement narrative context
- Review Change Proposals — Track substantive changes alongside narrative decisions
Pro Tip: When the AI assistant generates Change Proposals from an Artifact, it does not automatically capture architectural context — that’s your job. Before submitting the PRD for sponsor review, add a Design Principles block and an Architecture block. Reviewers who understand the constraints will give more targeted feedback.
Support
- Documentation: Continue reading about Initiatives and Requirements
- In-App Help: The AI assistant can help draft and organize narrative content
- Email: support@catalio.ai
- Community: Share PRD structure patterns with other Catalio users