Two sibling visualization jobs in one skill. GIRRAPH β IBIS discipline for mapping contested, fuzzy, or wicked problems as issues (β), positions (π‘), and arguments (β/β) in a .girraph file, BEFORE any solving happens; engage when the user wants to map a problem, untangle a decision with no clean answer, see the shape of a disagreement, or says 'girraph this', 'map this out', 'help me think through (not solve) X', 'what are the positions on Y', 'IBIS', 'argument map'. MERIRMAID β generate, display, and edit Mermaid diagrams in .merirmaid files for ANYTHING with structure or flow; engage when the user says 'diagram this', 'flowchart', 'mermaid', 'sequence diagram', 'state diagram', 'visualize this process', 'draw the architecture', 'show how X works', 'chart the steps'. Also engage when a planning conversation keeps circling β competing considerations that won't linearize are a girraph smell; a described-but-unpictured process or structure is a merirmaid smell. Do NOT engage for problems with a known procedure (use a request file), linear plans (use text-planning), or simple either/or questions the user just wants answered.
Two sibling jobs, one skill, both about turning something the user is holding in their head into an editable picture on disk:
.girraph file. The product
is a confirmed map, not a solution. This half is unchanged discipline;
it lives in the first part of this file..merirmaid file, rendered live
in the browser. The product is a diagram the user can read and edit.
This half lives in the second part.| The user wants to⦠| Use | Why |
|---|---|---|
| Untangle a question with no clean answer; see who believes what and why | .girraph | Contested framing, competing positions, arguments β that's IBIS. |
| Picture how something is put together, or how a process/interaction/lifecycle flows | .merirmaid | Structure and flow are Mermaid's job; there's a right answer to depict, not a debate to map. |
Rule of thumb: if the honest first move is asking a question (what's
really at issue here?), it's a girraph. If the honest first move is
drawing a box-and-arrow (here's how the pieces connect), it's a
merirmaid. When both apply β a contested decision and a system to
picture β they can coexist: map the argument in a .girraph, depict the
mechanism in a .merirmaid, and cross-link them (see linking, below).
IBIS (Issue-Based Information Systems) is a 1970s-vintage discipline for
mapping wicked problems β problems where the framing is part of the
fight, every stakeholder sees a different problem, and there is no
stopping rule. This skill teaches you to build that map as a girraph
(pronounced "graph"; the ir is for iterative/recursive) using the
girraph tools (read_girraph, add_node, update_node, link_nodes,
remove_node).
The product of this half is a confirmed map, not a solution.
? β) β a genuine open question, phrased as a question.
Not "the database problem" but "How should we store user data?".
If you can't phrase it as a question, it isn't an issue yet.! π‘) β one possible answer to exactly one issue.
A position responds to its parent issue; if it answers a different
question, you've discovered a new issue β add that first.+ β / - β) β supports or objects to exactly one
position. Arguments attach to positions, not to issues. An argument
that cuts across several positions gets one node plus link_nodes
cross-edges to the others.. π) β context that is none of the above: background
reading (ref: a doc), constraints, definitions, data points.@ π¦) β when a sub-question grows its own
positions-and-arguments thicket (rule of thumb: ~7+ descendants, or
the sub-debate has different stakeholders), split it into its own
.girraph file and link it with an @ node. Recursion is the
feature; don't let one file become a wall.Never propose interventions, resolutions, recommendations, or "so what we should do isβ¦" while the map is unconfirmed. The temptation is strongest exactly when it's most damaging β early, when the framing is still the user's biggest unknown. Record positions as positions on the map, including your own if asked, and keep mapping. If the user asks you to just solve it, say plainly: "Happy to β want me to finish the map first so we're solving the right problem? It's close." If they still want the answer, give it; they're the boss. But never drift into solving on your own initiative.
Wicked problems have no natural stopping point β that's what makes them wicked. The imposed rule: the map is done when the user says it's done. Offer a readiness check when the map stabilizes (no new nodes in a few exchanges): "Does this map capture the problem as you see it? Anything missing or mis-framed?" The user's confirmation is the finish line. After confirmation β and only then β solving can begin, in whatever paradigm fits.
by:user). Challenge it when (a) two of their
claims conflict, (b) a stated issue smuggles in a position ("How do
we ship the plugin API?" assumes shipping), or (c) the same words
carry two meanings in different branches. Challenge by asking, not
asserting β and if they hold, record their framing and move on.read_girraph on the working
branch; never assume the map is as you left it.read_girraph re-orients you.by:) β cheap now, load-bearing laterEvery position and argument gets a by:: user, agent, or a
readvisor slug. This is what keeps "whose claim is this?" answerable
months later, and it's the hook for stakeholder workflows β when
readvisors (or future synthesized stakeholders) weigh in, their nodes
carry their name, and a glance shows which voices have and haven't
been heard on each position. Never relabel someone else's claim as
your own; if you sharpen the user's wording, the node is still
by:user.
add_node with no parent β file created, label becomes title.
Default location: <slug>.girraph at the project root (or where
the user says).When the text-planning paradigm is active and this skill is enabled,
plan structure (the contested shape of the thing β what it's arguing,
what belongs in/out, order-of-battle questions) lives in a girraph at
the project root; the prose plan document stays the home for settled
decisions. Map first, settle into the plan after confirmation.
A merirmaid (pronounced "mermaid"; the ir is the same
iterative/recursive joke as girraph) is enough's flavor of a Mermaid
diagram: plain Mermaid source wrapped in a small frontmatter header,
saved as a .merirmaid file and rendered to SVG live in the browser
by a vendored Mermaid v11 (enough/static/mermaid.min.js, no CDN).
Plain text is the source of truth β a .merirmaid is never a stored
image.
Use this whenever the user wants to see a structure or flow: an architecture, a process, an interaction, a lifecycle, a data model, a schedule, a breakdown. If they described a system in words and would grasp it faster as boxes and arrows, offer to draw it.
UTF-8 text. key: value frontmatter between --- fences (first thing
in the file), then verbatim Mermaid source:
---
merirmaid: 1
title: How the broker gates a tool call
modality: wip
node-char-limit: 48
---
flowchart TD
A[tool call] --> B{broker toggle on?}
B -- yes --> C[runner executes]
B -- no --> D[canned denial]Frontmatter keys:
merirmaid: 1 β required, the format version.title β required, a human-readable name shown in the viewer
toolbar.modality β required, either wip or mirror (see below).node-char-limit β optional soft per-node-label limit the in-viewer
editor surfaces (defaults to 48). Not a hard cap.Everything after the closing --- fence is verbatim Mermaid source of
any diagram type Mermaid v11 supports.
wip vs mirror (know the difference)wip β a working diagram / brainstorming whiteboard. This is what
you create when the user asks you to diagram something. Node text is
user-editable in the viewer; structure edits come through you via chat.
Whole-file write_file is allowed for these.mirror β a source-of-truth diagram that mirrors some external
structure. It is read-only and owned by whatever backend generates
it. Never hand-write or edit a mirror file. The launch example is
the auto-generated mirror diagrams of a canon volume's
contents under ~/enough/canon/: a backend module owns those and
regenerates them on every change. If a user asks you to "fix" or "tidy"
a mirror diagram, don't β explain that it reflects the actual structure
and the way to change the picture is to change the thing it mirrors
(e.g. the volume's contents). write_file on a mirror file under
~/enough/canon/ is refused by the broker anyway; don't try to
route around it.Create modality: wip for everything you author. Only ever read
mirror files.
Pick the diagram type from what's being depicted:
flowchart TD (top-
down) β the default. Reach for it unless another type clearly fits
better; it's the format users read and edit most fluently. Use LR
(left-right) only when the flow is naturally horizontal.sequenceDiagram.stateDiagram-v2.classDiagram.erDiagram.gantt; simple proportion
breakdowns β pie; loose radiating brainstorms β mindmap.Full syntax for each type is vendored in references/ β read the page
for the type you're about to write rather than reconstructing syntax
from memory. references/README.md indexes them.
Label rules:
node-char-limit: 48, but generate well under it: users edit node
text in the viewer and need headroom to expand a label without
immediately tripping the warning. Short labels also render cleaner.
Put detail in the surrounding structure, not in one giant node.#, quotes, brackets, or a leading o/x. In flowcharts,
wrap the text: A["read_file (gated)"]. Unquoted punctuation is the
#1 cause of Mermaid parse errors.end as flowchart node text (capitalize it or
reword) β lowercase end breaks flowchart parsing.To make one diagram a drill-down from a node in another, use a Mermaid
click interaction with a relative path:
click NODE "subsystem/details.merirmaid"The viewer intercepts these clicks and pushes the target onto a
breadcrumb stack β the same navigation pattern as girraph mode's @
refs. Targets may be .merirmaid, .girraph, or .md paths. This is
how you keep any single diagram small: when a node deserves its own
diagram, give it one and click-link it rather than cramming everything
into one wall. A .merirmaid flowchart node can even link to a
.girraph when the sub-topic is contested rather than structural β
that's how the two halves of this skill connect.
.merirmaid files are plain text with no special tools:
read_file.write_file (whole-file writes are allowed for wip
files β there are no broker-assigned IDs to protect, unlike
.girraph).read_file at the start of an edit turn and rewrite from
what's actually there β never from your memory of the last version, or
you'll clobber the user's label edits.A wip merirmaid depicting how enough routes a chat turn between the
local model and the cloud slot, with one node linking off to a deeper
diagram:
---
merirmaid: 1
title: Chat turn routing
modality: wip
node-char-limit: 48
---
flowchart TD
U[user message] --> A[assemble system prompt]
A --> R{active model?}
R -- local --> L[llama-server stream]
R -- opro-api --> C[cloud stream]
L --> T{tool call?}
C --> T
T -- yes --> X[run tool via broker]
X --> A
T -- no --> E[end turn]
click X "broker-gating.merirmaid"Every node label is short, decision nodes use {β¦}, no label needs
quoting, and the click turns "run tool via broker" into a drill-down
to a broker-gating diagram. This parses against the .merirmaid
frontmatter rules: merirmaid: 1, title, and modality: wip are all
present and the body is valid Mermaid.
Map the disagreement, confirm the map, only then solve β or draw the structure so it can finally be seen. Read before you write, either way.
enough-tooltip-text: "use girraph-merirmaid to map hard, fuzzy, or contested problems as an editable issue/position/argument girraph, or to draw structures and processes as editable Mermaid diagrams in .merirmaid files."
0gsd/enough
3cf8a60
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.