id: fragment-writing-guide
prism: public-guide
scope: public
tags:
  - guide
  - writing
  - structure
  - prism
  - scene
title: How to write a clear Fragment — A practical guide

How to write a clear Fragment

A practical guide for structure-first writing

This guide shows how to compose a Fragment so that both humans and AI can read it consistently.
It introduces a repeatable writing pattern that works for weekly notes, research logs, design docs, and project briefs.

---

1. Start with front‑matter — keep it minimal

Every Fragment begins with a small, stable YAML block:

• id
• title
• scope (public / private)
• tags
• optional: a default prism profile

Front‑matter is not content.
It only sets identity, visibility, and high‑level metadata.

Example:

id: weekly-2025-02-03
title: Weekly note — Feb 3
scope: private
tags: ["weekly", "planning"]
prism: "work-editor"

---

2. Add a Prism block — tell AI how to read this page

A Prism block defines AI behaviour, tone, boundary, and interaction style.

You do not need to write prompts every time—Prism acts as the page’s “AI contract”.

persona:
  name: "Work editor"
role: "helps tighten reasoning and reveal next actions"
tone:
  style: "clear, concise"
  directness: "respectfully direct"
focus:
  avoid:
    - "vague summaries"
    - "therapy-like elaboration"
  emphasise:
    - "actionable phrasing"
    - "trade-offs and alternatives"

Prism stays close to the text, so AI always has the correct context.

---

3. Use Scene or Flow blocks when structure matters

Use a diagram block only when it adds clarity:

• timelines
• project flow
• weekly structure
• stakeholder map
• architecture overview

Example:

Scene stays as text, making it searchable, versionable, and AI‑readable.

---

4. Write the main narrative in Markdown

Markdown carries:

• context
• reasoning
• decisions
• examples
• tasks
• progress notes

A recommended order:

1. Context / premise
2. Current situation
3. Analysis / options
4. Decision
5. Next actions
6. Open questions / risks

Markdown is where humans read. YAML blocks support it, never replace it.

---

5. Keep each Fragment scoped to one unit of thought

A Fragment is intentionally small.
Use one page = one subject:

• one weekly note
• one project milestone
• one experiment
• one incident review
• one design decision

Large documents should be a collection of Fragments, not one giant page.

---

6. A complete small example

---
id: project-kickoff
title: Kickoff — Search system redesign
scope: private
tags: ["project", "kickoff"]
prism: "decision-editor"
---

persona:
  name: "Decision editor"
role: "helps clarify objectives and trade-offs"
tone:
  style: "neutral"
  directness: "balanced"

Narrative

Goal

Redesign the search system to improve retrieval speed and ranking stability.

Constraints

• existing index infra must remain unchanged for now
• response time must stay within 120ms

Success criteria

• stable ranking across updates
• fewer “empty result” cases
• measurable improvement in top‑5 relevance

---

7. Final advice

• Keep YAML blocks small.
• Keep narrative honest and readable.
• Let structure support thinking—not replace it.
• A Fragment is a thinking unit, not a document template.

---

If you follow this pattern, every page becomes:

• readable
• explainable
• AI‑consistent
• diff‑able
• future‑proof

A quiet, structured way to think with AI.

---

Getting started — from nothing to one page

Added 2026-08-07.

Starting from nothing

You don't need a system on day one. Write one page. Don't worry about structure or quality; the point is to have one place holding how things are today.

最初は 1 件だけで十分です。きれいにまとめる必要はありません。「いまの状態が 1 か所に置かれている」ことを優先してください。

Name it, tag it

Give it a short, honest title — "This week — rough notes" is a fine title — and two or three tags you will actually use later: journal, project, idea.

Keep the tag vocabulary small at first, around three to eight words. Choose the words you would actually search for, not the words that sound organised.

For how AI should respond on the page, add a small behaviour note — three lines is a reasonable start; see section 2 above and Prism Protocol.

Read the same page a second way

A page written with headings can be read as a deck as well as prose. Trying that once is a quick way to find out whether the structure you wrote is actually carrying the argument — if the headings don't work as a talk track, they probably aren't doing much in the prose either.

Habits that help

• Leave one small page a day. Three to five lines is enough.
• Keep the tag vocabulary small at first.
• Once a week, reread two or three old pages and add one new line to each.

Keeping it quiet

• Structure can change later. Early on, spend the attention on writing rather than sorting.
• Let AI in after you have written something, so your own voice stays visible in the page.
• For a page that matters, put a one-line "why now?" near the top. It is the line you will want when you reread it in six months.

Enough to begin

One real page beats a perfect setup. Today's situation, the current project, or a note about how you want to be helped — any one of those, one page.