v2.2 to v2.3

- version: "2.2"

- **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.

-

- - **`check-agent`** — fresh-context, read-only findings validator (`+check`). Expands to:

- Agent(subagent_type: Explore, model: sonnet, prompt: "<the criteria from references/coherence-gate.md>")

- `Explore` is read-only **by construction** — its tool set excludes `Edit`/`Write`, so the

- read-only contract is guaranteed by the dispatch, not merely requested in the prompt.

- Fallback: if the `Agent` tool is unavailable, run the pass yourself, inline — see

- `references/coherence-gate.md`

- (`WARN [coherence] fresh-context pass unavailable — running inline`). The gate is never

- skipped or delayed.

- - **`check-agent`** — fresh-context, read-only findings validator (`+check`). Expands to:

- Agent(subagent_type: Explore, prompt: "<the criteria from references/coherence-gate.md>")

- This runtime may offer no read-only-by-construction agent type, so the read-only

- contract rides on the prompt rather than on the dispatch: state it explicitly in the

- criteria you send from `references/coherence-gate.md`.

- Fallback: if the `Agent` tool is unavailable, run the pass yourself, inline — see

- `references/coherence-gate.md`

- (`WARN [coherence] fresh-context pass unavailable — running inline`). The gate is never

- skipped or delayed.

- When writing the `Next step:` field of `## Active Summary`, use this table to generate a

- specific follow-up instead of a generic "update other files". Example:

- - "Architecture decision: use Addressables pooling → run `/unikit-architecture` to formalize"

- - "New convention: all factories return UniTask → run `/unikit-rules` to codify"

- - **Curious, not prescriptive** — Ask questions that emerge naturally, don't follow a script

- - **Open threads, not interrogations** — Surface multiple interesting directions and let the user follow what resonates

- - **Visual** — Use ASCII diagrams liberally when they'd help clarify thinking

- - **Adaptive** — Follow interesting threads, pivot when new information emerges

- - **Patient** — Don't rush to conclusions, let the shape of the problem emerge

- - **Grounded** — Explore the actual codebase when relevant, don't just theorize

- **Explore the problem space**

- - Ask clarifying questions that emerge from what they said

- - Challenge assumptions

- - Reframe the problem

- - Find analogies from game development

-

- **Investigate the codebase**

- - Map existing architecture relevant to the discussion

- - Find integration points and Zenject bindings

- - Identify patterns already in use (DI containers, signals, factories)

- - Surface hidden complexity and coupling

- - Trace data flow through systems

- **Fallback:** If Agent tool is unavailable, use Glob/Grep/Read directly.

-

- **Compare options**

- - Brainstorm multiple approaches

- - Build comparison tables

- - Sketch tradeoffs (performance, complexity, extensibility)

- - Recommend a path (if asked)

-

- **Surface risks and unknowns**

- - Identify what could go wrong

- - Find gaps in understanding

- - Suggest spikes or investigations

- - Flag performance concerns

-

- This step has **no exceptions**. It used to have exactly one — `init` rebuilt the researches

- index and needed no project context — and that mode no longer exists: the registry is

- re-rendered as part of every save. The absence is recorded here rather than left silent,

- because a MANDATORY step that once had a hole reads like an oversight when the hole simply

- closes.

-

- When the exploration topic involves a library or framework from the project's tech stack,

- assess whether the loaded Stack rules provide enough information:

-

- 1. **Stack rule loaded and covers the topic** → proceed with available knowledge, no external lookup needed.

-

- 2. **Stack rule loaded but doesn't cover the specific question** (user asks about

- API methods, configuration options, or features not described in the rule) →

- keep the rule for project conventions, additionally query context7 for the

- specific API documentation gap.

-

- 3. **No matching stack rule exists** but the topic involves a library/framework

- from the project's tech stack (check `DESCRIPTION.md`) → query context7 as the

- primary documentation source for that library.

-

- **context7 query flow:**

- 1. `mcp__context7__resolve-library-id` — find the library ID.

- 2. `mcp__context7__query-docs` — focused query matching the specific aspect the user

- is exploring (not a broad "everything about X" — target the concrete question).

-

- **Fallback:** If context7 tools are unavailable or the lookup fails — proceed with

- your own training knowledge, but explicitly tell the user that the information was not

- verified against current documentation and may be outdated.

-

- **Priority:** Stack rules (project conventions — "how we use it here") always take

- precedence over context7 / web results (API reference — "what the library offers").

- When both are loaded, use stack rules for coding patterns and project-specific decisions,

- and external docs for API details and feature capabilities.

-

- **Mid-exploration enrichment:** If the topic shifts during exploration and a new library

- becomes relevant — apply the same logic at that point. Don't wait until the next full

- context bootstrap.

- - `.unikit/ROADMAP.md` — strategic milestones (if any). If ROADMAP.md contains a `## References` section with linked documents, and the exploration topic relates to a specific milestone — read the reference documents associated with that milestone (listed in the `Milestones` column of the References table). This provides the original requirements/design context behind the milestone without asking the user for additional input.

- - **Game-design grounding** (only if a design workspace exists) — check `.unikit/gamedesign/GD-IDS.yaml`. **Schema guard:** it MUST be `version: 2` — on a pre-v2 `version: 1` registry, skip design grounding and emit a loud `WARN [design] GD-IDS.yaml is version 1 (pre-v2 layout); design grounding skipped` rather than silently misreading the old layout. When valid, **load the shared READ contract** `.unikit/system/gamedesign/design-read.md` and apply it: its **read surfaces** (read the registry — system `doc_status`/`version`/`depends_on`, flow `mode`/`goals`/`depends_on`, content `scale`/`belongs_to`/`fields` — and follow each entry's `source` path to `.unikit/gamedesign/systems/*.md` / `.unikit/gamedesign/flows/*.md` / `.unikit/gamedesign/content-types/*.md`; the human-readable views are GAME.md's `## System Map [gen]` / `## Flow Map [gen]` / `## Content Map [gen]`), its **Flow-First Resolution** (*intent decides the door*), and its **one-way boundary**. **First-class flow input:** when the exploration topic names or implies a **flow** (a player-facing sequence, onboarding / progression / pacing, a `FLOW-<slug>` id), ground **first-class on that flow** — not merely as a reactive add-on to a system; a system-shaped topic grounds on the system; ambiguous → ask (per design-read). An empty `flows: []` (or no `flows` key yet) → skip the flow read silently, never an error. **First-class content input:** when the topic names or implies a **content type** (a catalog, "the item types", a `CT-<slug>` id), ground **first-class on that content type** via the content door of the design-read ladder — its `CT.fields` schema, `scale`, and `belongs_to`; an empty `content_types: []` (or no `content_types` key) → skip the content read silently, never an error. **One-way boundary: explore may *read* design for grounding; it never writes or edits design — that flows through the `/unikit-gd-*` skills.**

-

- ### Why this matters

-

- Without this context you'll give generic {{engine_name}} advice instead of advice grounded in this project's actual architecture, conventions, and patterns. The quality difference is enormous — this is the foundation that makes explore mode valuable.

- - **The slug of an existing research folder** in `.unikit/code/researches/` — this is an

- **entry into the continuation cycle**, not a new topic. Read the manifest and continue that

- research (see [Continuing a research](#continuing-a-research)).

- - A vague idea: "object pooling system"

- - A specific problem: "the save system is getting unwieldy"

- - A system name: to explore its architecture

- - A flow or player sequence: "the first-session flow", "the onboarding", a `FLOW-<slug>` id — a **first-class flow input** that grounds on the dynamics axis (per the design-read Flow-First Resolution)

- - A content type or catalog: "the item types", "the loot catalog", a `CT-<slug>` id — a **first-class content input** that grounds on the catalog axis (per the design-read Flow-First Resolution)

- - A comparison: "UniTask vs coroutines for this"

- - A question: "how does the DI container handle scene transitions?"

- - Nothing: just enter explore mode

-

- If the argument matches the name of an existing folder in `.unikit/code/researches/`, treat it

- as a continuation rather than a new subject, and follow

- [Continuing a research](#continuing-a-research).

- └── [adaptive artifacts] ← ultra only

- ├── CONTRACTS.md

- ├── C4-CONTEXT.md

- ├── C4-CONTAINER.md

- ├── C4-COMPONENT-<scope>.md

- ├── DEPENDENCY-GRAPH.md

- └── ADR-NNNN-<slug>.md

- - The date lives in the `Created:` and `Updated:` fields of the manifest header, which is

- also where every age filter and all sorting read it from.

- - The reason the date left the name is structural, not cosmetic: a dated folder makes the

- continuation cycle impossible to express. `<date>-<slug>` cannot be *continued* tomorrow

- without the name becoming a lie, so the format would quietly push every follow-up into a

- second folder — which is exactly the duplication this format exists to remove.

- **If that slug already names a folder in `.unikit/code/researches/`**, do not resolve it

- silently. Ask:

- - *Continue* → enter [Continuing a research](#continuing-a-research); print

- suffix (`-2`) is **forbidden**: the date used to be a separator as well as a sort key, and

- a silently appended suffix is what makes addressing-by-meaning start finding the wrong

- folder again. Refusing outright is not an option either — a continuation verb exists here,

- and offering it costs less than a refusal.

- The order of writing is owned by `{{skills_dir}}/{{self_name}}/references/ULTRA-RESEARCH-FORMAT.md` → `## Write order`, and it is not restated here. **In a standard research, items 1 and 5 — the adaptive artifacts and the Integrity checks — simply do not apply**; the rest of the order holds unchanged, including that the registry is re-rendered before the gate runs.

- **In ultra mode** the artifacts are written first and `RESEARCH.md` second. Writing the index of artifacts before the artifacts would point its links at files that do not exist yet.

- **In ultra mode**, the very first line of the file is the research mode marker `<!-- unikit:research-mode:ultra -->`, and a `## Artifact Index` section follows immediately after `## Table of Contents`. Both are specified in `references/ULTRA-RESEARCH-FORMAT.md`; neither is restated here.

- Requirements: <`REQ-<n>` — established by evidence>

- Decisions: <`DEC-<n>` — taken, each with its reason in one line>

- sub-sections — not a copy of the template above. Research documents get long, and the TOC is

- how both humans and agents reach the section they need.

- other refers to it by ID, never by retelling it.

- **Language Awareness for `RESEARCH.md`**: the manifest follows the same language rules as

- every other artifact. When the configured language is not English, translate section headings

- and prose into the target language. Field **names** in the header (`Created:`, `Status:`,

- `Lifecycle:`, …), the marker comments, ID prefixes, code identifiers, code blocks and file

- paths stay in English — they are read by machines.

- **Where the previous sections went.** The retired three-file format put seven owning sections

- in its result document. They are gone *as owners* and their content is redistributed; recorded

- here so the next edit does not restore them "for completeness":

- | Previous section | New owner |

- |------------------|-----------|

- | `## Topic` | `## Active Summary` → `Topic:` |

- | `## Context` | `## Active Summary` → `Goal:` / `Scope:` |

- | `## Exploration` | `## Findings` |

- | `## Conclusions` | `## Findings` for the reasoning; `## Active Summary` → `Requirements:` / `Risks:` for the requirement |

- | `## Decisions` | `## Active Summary` → `Decisions:` (`DEC-<n>`) |

- | `## Open Questions` | `## Active Summary` → `Open questions:` (`OQ-<n>`) |

- | `## Next Steps` | `## Active Summary` → `Next step:` |

- | `## References` | stays its own section, at the end |

- `## References` stays standalone rather than folding into `## Findings` on purpose: `## Findings`

- is the section that grows without bound, and a reference list buried inside it stops being

- findable.

- ### SOURCE.md for prompt-based explorations

- If the exploration was **prompt-based** (see [Exploration mode detection](#exploration-mode-detection)), generate an additional artifact `SOURCE.md` in the same research directory. This file captures the full dialogue context so that the exploration can be reproduced or continued later without losing any context.

- `SOURCE.md` is a **log, not a derived representation of the research.** Two consequences,

- both deliberate: it is **not** part of the hashed region (only `## Active Summary` inside

- `RESEARCH.md` is), and it is **not** in the coherence gate's durable scope. A log is allowed

- to be redundant with the manifest — that is what a log is for, and admitting it to the gate

- would hand back exactly the job of reconciling two differently-written texts.

- **When to generate**: Only for prompt-based explorations (user gave a topic/question/idea without referencing specific documentation files). Do NOT generate for file-based explorations (user referenced specific files/folders as input documentation).

- **Answer**: <The answer that was given — by user or discovered during exploration>

- **Answer**: <The answer>

- <All additional details, corrections, and clarifications the user provided during the exploration that were not direct answers to questions. If none — write "None">

- <The final result of the exploration: what was decided, what approach was chosen, what understanding was reached. This should be a concise summary of the outcome, not a copy of RESEARCH.md>

- answers and clarifications. Everything already in the file stays exactly as it is. The point

- of a dialogue log is that it records what was actually said at the time, and an edited log

- records only what the last session believed.

- **Language Awareness**: Follow the same language rules as other artifacts. Translate section headings and prose into the configured language. Keep code identifiers and file paths in English.

- **Important**: Capture the actual dialogue content faithfully. The value of this artifact is in preserving the exact questions, answers, and clarifications — not in summarizing or rephrasing them.

- appended to: on every save it is re-rendered whole from the folders on disk, so it cannot fall

- behind them.

- 3. A folder with no readable `RESEARCH.md` is skipped, and the skip is **printed**:

- Skipping in silence is forbidden. An unreadable manifest and an honestly empty registry

- look identical from the outside, so an unannounced skip reports "no researches" for a

- research that is sitting right there on disk.

- 7. After the re-render, print the reconciliation summary — the same three lines the retired

- `init` command printed:

- **Reconciliation is no longer a separate verb.** There used to be an `init` argument whose

- whole job was to rebuild this file from disk; it is gone, and its work is now part of every

- save — the same pattern as `syncRulesState` Phase 1 and the `## System Map [gen]` re-render in

- game-design. It stopped being a separate command, but it did **not** stop being **visible**,

- which is what step 7 is for.

-

- The cost is worth naming: the registry can no longer be repaired by a dedicated command. In

- exchange it can no longer fall behind, because it is rebuilt from the folders — the actual

- source of truth — before the coherence gate reads the same files from disk.

- `researches/INDEX.md` — and **before** confirming the save to the user, read

- `{{skills_dir}}/{{self_name}}/references/coherence-gate.md` and run the gate it specifies as a `check-agent` dispatch.

- The read is conditional: this is the only moment the file is needed, so it is not loaded at

- the start of an exploration.

- Its position is fixed: **after Step 4, before Step 5.** The order matters in both directions.

- The gate re-reads the durable files from disk, so running it before the write has nothing to

- read; and confirming before it runs tells the user the research is safe while it may still be

- incoherent.

- In ultra the gate runs **after** the bundle integrity checks, not instead of them.

- If `references/coherence-gate.md` cannot be read, print one line

- `WARN [coherence] reference missing — saving without the coherence pass` and continue — the

- same trade as the ultra reference above: the research has already been done and written, and

- losing it over a missing reference file is not acceptable.

- Only once the gate has **finished** — passed, or stopped at its budget with the user's answer

- in hand — tell the user what was written: the folder, the manifest, any adaptive artifacts,

- and the registry line. Until then the save is not confirmed — a gate that runs after the

- confirmation is a gate that reports on a decision already announced.

- - **Don't auto-save** — Always offer and let the user decide

- - **One manifest** — `RESEARCH.md` carries the research. There is no second canonical file and

- no brief: `## Active Summary` *is* the machine input, and `## Findings` holds the evidence

- that produced it

- - **`SOURCE.md` only for prompt-based explorations** (see [SOURCE.md for prompt-based explorations](#sourcemd-for-prompt-based-explorations)), appended to on a continuation, never rewritten

- - **The registry is re-rendered whole on every save** — never edited, never appended to; this

- is how other skills discover researches, and how it stays in step with the folders

- - **Run the coherence gate** — it is part of saving, not an option. It runs *after* the user has agreed to save, so it neither replaces the question nor weakens `Don't auto-save`

- ## Continuing a research

-

- A research is not finished when it is saved — it is **continued**. This is the reason the

- folder name carries no date.

-

- **Entry.** Either the argument named an existing folder in `.unikit/code/researches/`, or the

- user chose *Continue the existing research* in the collision dialogue during a save.

-

- **Procedure.**

-

- 1. Read the folder's `RESEARCH.md` in full — the header, `## Active Summary`, `## Findings`

- and every past `## Sessions` entry. In ultra, read the files in `## Artifact Index` too.

- 2. Explore further, exactly as in a fresh session.

- 3. When saving:

- - **Append** a new entry to `## Sessions`, immediately **before** the closing marker.

- Past entries are reproduced verbatim — the section is append-only.

- - Move `Updated:` to now (from `date`). `Created:` never changes.

- - **Revise `## Active Summary` in place.** New IDs continue the existing numbering; an ID

- is never reused; a superseded item **keeps its number**, is marked superseded, and names

- what replaced it. Revising the summary is the point of a continuation — a session that

- only appends to `## Findings` has recorded evidence without ever updating the conclusion.

- - Reconsider `Status` and `Lifecycle` **explicitly**, and say what they became. Neither

- carries over by default; a research that has quietly stayed `in-progress` across four

- sessions is telling the registry something nobody decided.

- - Append the session's dialogue to `SOURCE.md` if the exploration is prompt-based.

- - Re-render the registry and run the coherence gate, exactly as on a first save.

- 4. **Say it out loud when the folder has outgrown its question.** From the fourth session, or

- past fifteen artifacts, print one line and continue — a note, never a gate:

-

- ```

- NOTE: 4th session, 17 artifacts — a research that keeps growing past its original question

- is cheaper to close and restart with `Supersedes:` than to extend.

- ```

-

- The threshold counts **sessions**, not artifacts: repeated passes are what multiply the

- carriers of one value. A large folder written in one sitting is not the problem this note

- is about.

-

- **Superseding a whole research.** When a new research replaces an old one rather than

- continuing it, the new one carries `Supersedes: <slug>` in its header and the old one is set

- to `Lifecycle: superseded`. The superseded folder is **not deleted** — it is the trace of the

- reasoning, and removing it makes the replacement look unmotivated.

-

- ---

-

-

- ## What You Don't Have To Do

- - Follow a script

- - Ask the same questions every time

- - Produce a specific artifact

- - Reach a conclusion

- - Stay on topic if a tangent is valuable

- - Be brief (this is thinking time)

- **User brings a vague idea:**

- ```

- User: I'm thinking about adding an object pooling system

-

- You: Object pooling is a broad space in {{engine_name}}. Let me think about this...

-

- POOLING APPROACHES IN {{engine_name}}

-

- Simple Managed Advanced

- | | |

- v v v

- +--------+ +---------+ +----------+

- |Queue<T>| |Pool with| |Addressable|

- | Manual | |Auto-grow| | + Pool |

- | return | |+ Limits | | Async Load|

- +--------+ +---------+ +----------+

- | | |

- trivial moderate complex

-

- What are you pooling? Projectiles? UI elements? Enemies?

- ```

-

- **User brings a specific problem:**

- **User wants to compare options:**

- ```

- User: UniTask vs Coroutines for our async loading?

-

- You: Context matters here. Let me check what you're already using...

-

- [reads codebase, finds patterns]

-

- +----------------------------------------------+

- | ASYNC PATTERNS IN YOUR PROJECT |

- +----------------------------------------------+

-

- Coroutines UniTask

- Cancellation manual CancellationToken

- Error handling silent fail try/catch

- Return values callback await result

- Testability hard easy

- Zenject DI awkward natural

- Performance GC alloc zero-alloc

-

- You already use UniTask in 3 systems. Consistency

- alone makes the case. But there's more...

- ```

-

- **User is stuck mid-implementation:**

- ```

- User: /unikit-explore save-load-system

- The serialization is more complex than expected

-

- You: [reads plan from .unikit/code/plans/]

-

- You're on task 4: "Implement save serialization"

-

- Let me trace what's involved...

-

- [draws diagram, explores options, suggests paths]

- Want to capture this as a research for reference?

- ```

-

- ---

-

- ## Guardrails

-

- - **Don't implement** — Never write feature code. Saving research files is fine, writing application code is not

- - **Don't fake understanding** — If something is unclear, dig deeper

- - **Don't rush** — Discovery is thinking time, not task time

- - **Don't force structure** — Let patterns emerge naturally

- - **Don't auto-save** — Offer to save research, don't just do it

- - **Do visualize** — A good diagram is worth many paragraphs

- - **Do explore the codebase** — Ground discussions in reality

- - **Do question assumptions** — Including the user's and your own