Workflows

ADR Decision

Structural decision workflow: from identified tension to trace in the index.

When to use it

When a structural tension is identified — a technical choice, an architecture change, an arbitration between two incompatible approaches. Any persona can initiate the process.

Steps

1. Tension identified — a persona observes a problem, an inconsistency, or a choice to make. They formulate the tension in one sentence
2. Note deposited in shared/ — the persona deposits a note (cf. protocol/exchange.md) describing the context, identified options, and their recommendation
3. Multi-persona review — each concerned persona produces a review on their axis: architecture (consistency), dev (feasibility), research (rigor), UX (user impact), strategy (positioning)
4. ADR drafting — the architect drafts the ADR with Proposed status: context, decision, consequences, rejected alternatives
5. Orchestrator arbitration — the orchestrator moves the ADR to Accepted or Rejected. The decision is traced with its context
6. Trace in the index — the ADR is added to the index with status, summary, and date

Roles involved

Artifacts produced

• Initial note (in shared/notes/)
• Reviews by axis (in shared/review/)
• ADR in standard format: Context, Decision, Consequences, Status
• Entry in the ADR index

Pitfalls

• Coding on a Proposed ADR — a Proposed ADR is not an authorization. Only the Accepted status authorizes implementation. Coding before orchestrator arbitration means investing time on a decision that may be rejected
• ADR without alternatives — an ADR that doesn't list rejected alternatives is not an ADR, it's an announcement. The context of alternatives is what makes the decision understandable in 6 months
• Confusing tension and preference — a tension is an objective problem (inconsistency, blockage, incompatible choice). A preference is subjective. ADRs address tensions, not preferences

Dev Spec-First

Development workflow: never code without a validated target.

When to use it

For every feature, fix, or refactoring that touches product code. Applies as soon as an item is prioritized by the orchestrator.

Steps

1. The orchestrator prioritizes — the item exists in the roadmap with an explicit owner
2. Architect specifies — interface contract, constraints, ADR if structural decision (cf. protocol/exchange.md for formats). The spec is the contract: it defines the what, not the how
3. Dev plans in plan mode — feature-by-feature decomposition, each step confronted with principles and existing ADRs
4. Tests first (TDD) — write tests before code, by layer: engine/operators = strict TDD, CLI/UI = tests after implementation
5. Code — implement following module responsibilities and project conventions
6. Architecture review — the architect verifies consistency with the spec and principles. Gaps documented, not ignored
7. Commit — the dev prepares the message, the orchestrator executes

Roles involved

Artifacts produced

• Spec or interface contract (in the architect's workspace)
• ADR if structural decision (cf. decision-adr.md)
• Unit / integration tests
• Code + commit

Pitfalls

• Coding before the spec — "I know what needs to be done" leads to avoidable refactoring. The spec forces laying out constraints before touching code
• Confusing plan and spec — a plan decomposes steps, a spec defines a contract. A plan without a spec produces code without a target
• Skipping the architecture review — the review is not a formality. It detects gaps between spec and implementation before they propagate

Distillery

Field observations flow up into the method. Experience reports become documented patterns.

Structure

The cycle has three phases:

1. Observation: a learning, a friction, or a REX is documented in feedback/ or in a session summary. This is raw material, tied to a specific context.
2. Extraction: the orchestrator or a persona identifies what is universal in the observation — what would repeat in another context.
3. Integration: the extracted pattern is formalized and integrated into core/ or doc/. It becomes a piece of the method, decoupled from its original context.

The distillery is what differentiates a collection of notes from a living method. Without this mechanism, learnings remain scattered and non-reusable.

When to recognize it

• An observation in feedback/ is cited multiple times in different contexts.
• A previously encountered problem reappears — a sign it wasn't capitalized.
• An intuitively made decision deserves to be made explicit as a principle.

Example

The observation that personas should be defined by their production medium (documented in feedback/persona-calibration.md) was extracted and formalized as the pattern media-calibration.md. The original feedback remains in feedback/ as a trace; the pattern lives in canvas/patterns/.

Variants

• Reverse distillery: an existing pattern is invalidated by the field. The feedback documents the deviation, the pattern is amended or withdrawn.
• Cross-distillery: an observation from one domain (e.g. architecture) produces a pattern applicable in another (e.g. team method).

Risks

• Over-generalization: transforming a one-off observation into a universal pattern too quickly.
• Fossilization: a documented pattern is never questioned even when the field evolves.
• Accumulation without extraction: feedbacks pile up but nobody distills them.

Documentation

Documentation production workflow: from raw material to publishable doc.

When to use it

For any method or product documentation that must be both structurally complete and pedagogically accessible. Applies when the subject is complex enough to require separation between structure, field, and pedagogy.

Steps

1. Structuring — the architect produces a structural document from raw material (specs, ADR, code, sessions). Substance and exhaustiveness come first. No pedagogy concerns at this stage
2. Field analysis — the practitioner reads the document against the field (historical sessions, real usage, prescription/practice gaps). They note the gaps, the points where the doc doesn't match what actually happens
3. Pedagogical proposal — the pedagogue analyzes the structured document + field feedback and produces an approach proposal (reading path, progressive examples, target profile, reformulations)
4. Convergence through challenge — the orchestrator has the practitioner challenge the pedagogical proposal. Iterative loop until convergence: the field validates that pedagogy doesn't betray reality, the pedagogue adjusts
5. Final validation — the orchestrator verifies integrity (substance is not betrayed by form) and arbitrates remaining tensions

Roles involved

Artifacts produced

• Structural document (in the architect's workspace)
• Field note (in shared/notes/ — practitioner → pedagogue)
• Pedagogical proposal (in shared/notes/ — pedagogue → orchestrator)
• Final document (in the product repo)

Pitfalls

• Pedagogizing too early — if the structure is incomplete, pedagogy masks the gaps. The structural document must be exhaustive before the pedagogical pass
• Field ignored — a document that doesn't match real usage won't be applied. The practitioner is the safeguard
• Pedagogy that betrays substance — simplifying is not distorting. That's why the practitioner challenges the proposal, not the architect (who is too close to the material to judge readability)
• Infinite loop — convergence must be bounded. If after 2-3 iterations the practitioner and pedagogue don't converge, the orchestrator decides

Escalation by note

When a persona encounters a problem outside their scope, they deposit a note. The orchestrator routes.

Structure

1. A persona identifies a problem that doesn't fall under their axis.
2. They write a factual note in shared/notes/ with the format note-{recipient}-{subject}-{author}.md.
3. They don't attempt to resolve the problem themselves.
4. The orchestrator reads the note, adds the necessary context, and forwards it to the competent persona.
5. The recipient handles it and responds via the same mechanism if needed.

There is no direct inter-persona communication. The orchestrator is the sole router. This preserves context isolation and prevents unsupervised coordination loops.

When to recognize it

• A persona hits a question outside their scope.
• Two personas would need to coordinate on a cross-cutting subject.
• A problem detected in one workspace concerns another workspace.

Example

Axel identifies an inconsistency in the CVM spec during implementation. He deposits note-mira-inconsistency-spec-cvm-axel.md in shared/notes/. The orchestrator reads, confirms the context, and opens a session with Mira (architecte) to address the point. Mira corrects the spec or justifies the existing choice.

Variants

• Informational note: no problem to solve, just a signal (e.g. "I observed that..."). The orchestrator decides whether there's a follow-up.
• Urgent note: the persona signals a blocker in the title. The orchestrator prioritizes.

Risks

• Orchestrator congestion: too many unprocessed notes accumulate. The orchestrator must sort regularly.
• Over-formalism: depositing a note for a trivial detail the persona could ignore.
• Context loss: the note is too short and the orchestrator can't route correctly.

Persona Onboarding

New persona integration workflow: from observed gap to first productive session.

When to use it

When a domain is not covered by existing personas and this gap generates recurring problems. This workflow is the process version — for the technical checklist, see doc/guides/getting-started.md §Part 3.

Steps

1. Gap observed — a domain emerges that nobody covers, or two personas are in recurring tension on a subject. The gap is documented, not assumed
2. Persona file definition — shared/orga/personas/persona-{name}.md: role, stance, scope, prohibitions, preferred media. Prohibitions are more important than responsibilities: what the persona doesn't do defines them as much as what they do (cf. core/principles.md, isolation principle). Template: instance/artifacts/persona.md
3. Context file definition — shared/orga/contextes/contexte-{name}-{product}.md: key documents, workspace scope, isolation, conventions, workflow. One file per persona×product pair (a same persona can have multiple contexts). Template: instance/artifacts/product-persona-context.md
4. Workspace creation — {workspace}/sessions/ + CLAUDE.md with 2 lines pointing to persona + context. The workspace follows instance conventions (cf. protocol/conventions.md § "CLAUDE.md — anatomy")
5. Calibration — first exchanges with the orchestrator and adjacent personas. Stance, vocabulary, and detail level adjustment. Calibration takes 2-3 sessions
6. First productive session — the persona produces a real artifact (review, note, spec) that is used by another persona. This is the validation criterion

Roles involved

Artifacts produced

• Persona file — shared/orga/personas/persona-{name}.md (draw from archetypes in instance/archetypes/ and format in instance/artifacts/persona.md)
• Context file — shared/orga/contextes/contexte-{name}-{product}.md (template: instance/artifacts/product-persona-context.md)
• CLAUDE.md — 2-line routing to persona + context
• Complete workspace ({workspace}/sessions/)
• Announcement note in shared/notes/ to inform other personas
• First productive artifact (review, note, spec)

Pitfalls

• Creating by symmetry — "we're missing a persona X to complete the team". A persona must prove its necessity through a real gap, not a theoretical symmetry
• The catch-all persona — if you can't say what it doesn't do, it's not calibrated. Prohibitions are the first quality test of a persona file
• Skipping calibration — an uncalibrated persona produces unusable artifacts. The first 2-3 sessions are an investment, not a waste of time
• Forgetting the context file — without context, the persona doesn't know their workspace. The persona knows who they are, the context tells them where they are

Product Chain

Complete production chain: every step has a guardian, no shortcuts.

When to use it

For any feature or evolution that crosses multiple domains — from prioritization to delivery. This is the reference workflow when multiple personas are involved.

Steps

1. The orchestrator prioritizes — the item enters the roadmap with context and owner
2. Architect specifies — contracts, constraints, ADR if needed. Guardian: consistency with target architecture and principles (cf. core/principles.md)
3. Dev implements — plan mode, TDD, code. Guardian: conformity to the spec
4. UX challenges — UX verifies user experience, accessibility, visual consistency. Guardian: the product is usable, not just functional
5. Research verifies — formal verification, sources, rigor. Guardian: what is claimed is true and correctly contextualized
6. The orchestrator arbitrates — last gate. Final validation, go/no-go

Roles involved

Artifacts produced

• Prioritized roadmap item
• Spec / interface contract
• Code + tests
• UX review (note in shared/review/)
• Formal validation if applicable
• Documented orchestrator decision

Pitfalls

• Skipping a step — every skipped step generates debt. The most costly debt is the one you don't see (cf. protocol/traceability.md)
• Parallelizing without a contract — dev and UX in parallel without a shared spec = two divergent visions to reconcile after the fact
• Confusing orchestrator validation with automatic approval — the orchestrator is the last gate, not a rubber stamp. They can send back to any step

Publication

Publication workflow: from writing to going live.

When to use it

For any published content — web page, public document, white/blue book, external communication. Applies as soon as content leaves the internal scope.

Steps

1. Writing — the writer or expert produces the raw content. Substance takes priority over form at this stage
2. Substance validation — concerned experts validate each on their axis (technical, strategic, formal). Each axis produces a review
3. Formatting — the producer (designer, integrator) formats. Structure and style follow the target medium's conventions
4. UX / accessibility challenge — UX verifies readability, navigation, accessibility. The content must work for the target audience
5. Orchestrator go — last gate. The orchestrator verifies factual integrity: what is published is true, sources are correct, positioning is right
6. Going live — effective deployment. The orchestrator executes or authorizes

Roles involved

Artifacts produced

• Draft (in the writer's workspace)
• Reviews by axis (in shared/review/)
• Formatted content (in the target medium)
• Orchestrator validation (implicit: the go is the commit/deployment)

Pitfalls

• Publishing without substance validation — formatting gives an illusion of quality. A well-presented but factually wrong document is worse than a correct draft
• The orchestrator validates form, not substance — the orchestrator's role at the last gate is specifically factual integrity. Form was validated before
• Unverified sources — a reference cited without having been fully read propagates errors in everything that cites it afterwards (cf. research.md)

Research

Research workflow: from source identification to usage verification.

When to use it

Every time a document cites an external source — article, paper, documentation, specification. Also applies when a persona states a fact that requires a reference.

Steps

1. Source identification — spot relevant sources for the subject. Favor primary sources (original paper, official spec) over secondary sources (blog posts, tutorials)
2. Complete source reading — read the source in full, not just the abstract or cited section. A partially read source is a misunderstood source
3. Contextualization — explicitly formulate why this source is relevant to this subject. What is the link between what the source says and what we want to show
4. Usage context verification — the critical question: does the source actually say what we make it say? Verify that the source's original context matches the usage we make of it

Roles involved

Artifacts produced

• Source review (in shared/review/, format review-sources-{subject}-{author}.md)
• Contextualization notes if necessary
• Corrections in citing documents if a source is misused

Pitfalls

• Factual contamination — a poorly contextualized reference propagates an error in all documents that cite it. This is the most costly error: it is invisible and multiplies
• Citing without reading — citing a source based on its title or abstract. The actual content may contradict the usage being made
• Confusing authority and relevance — a source can be reliable (recognized author, serious journal) without being relevant to the usage context. The review quality depends on the question asked, not just the source (cf. protocol/exchange.md)

Star Review

An artifact is submitted to N personas in parallel, each reviews it on their axis. The orchestrator consolidates.

Structure

1. The orchestrator identifies an artifact that requires multi-angle validation.
2. They submit it simultaneously to N personas, each with a review instruction on their own axis.
3. Personas produce their reviews in parallel, without reading each other.
4. The orchestrator collects the reviews, identifies convergences and contradictions, and consolidates a decision.

The difference with the challenger pattern: the challenger fits into a sequential production flow (the producer integrates the feedback). The star review is a one-off validation mechanism — reviewers don't modify the artifact, the orchestrator decides.

When to recognize it

• A structural document (ADR, spec, plan) must be validated before adoption.
• Multiple quality axes are at stake and no persona covers them all.
• Independent perspectives are wanted, not contaminated by others' opinions.

Example

The orchestrator submits an ADR to Mira (consistency with target architecture), Léa (recherche) (formal rigor, references), and Marc (strategie) (strategic alignment). Each produces an independent review in shared/review/. The orchestrator reads all three, identifies a tension point between architectural consistency and strategy, and decides.

Variants

• Partial star: only 2 of N axes are solicited, depending on the artifact's nature.
• Iterative star: after consolidation, the artifact is amended and resubmitted for a second round.

Risks

• Redundancy: reviewers inadvertently cover the same ground — wasted time.
• Paralysis: reviews diverge and the orchestrator can't decide.
• False parallel: reviews are launched "in parallel" but are actually sequential (one persona reads another's review before producing their own).