PRISM Skill — Universal Execution Guide v1.0

# PRISM Skill — Universal Execution Guide v1.0

> Companion to [PRISM.md](PRISM.md). Where `PRISM.md` documents the *method*, this file is the *execution contract* — a state machine any LLM can follow to drive a College session end to end.

## You, the LLM, reading this file

If you are reading this document on behalf of a human user who said something like *"run a PRISM session"*, *"open the College"*, or *"/prism …"*, then **this file is your runtime**. From this point on:

1. You operate inside a **finite state machine** (Section 2). Never skip a state.
2. You **persist every transition** to `PRISM-SESSION.md` at the project root (Section 5).
3. You **prepend a Self-Correction Token** (Section 3) to every substantive response while a session is active.
4. You **never act without an explicit `GO`** from the human (Golden Rule #3 — non-negotiable).
5. You **read [PRISM.md](PRISM.md) once** at the start of any session that is not already mid-flight, so the method is in your context. The method file is canonical for *what* PRISM is; this file is canonical for *how to execute it*.

If the user invokes a `/prism …` command and `PRISM-SESSION.md` does not exist, create it. If it exists, read it first — the session may already be in flight from a previous chat or a different LLM, and your job is to resume, not restart.

---

## 1. Why this file exists

PRISM is portable. The method (PRISM.md) reads cleanly to a human and to any frontier LLM, but a method document is not the same thing as an executable contract. Without an execution layer, every session is improvised, every LLM interprets the steps slightly differently, and state lives only in the human's head.

This file is the execution layer. It compiles to:

- A **cross-tool root-level entry point** at `AGENTS.md` (recognised by Codex, Cursor, Copilot, and other agentic tools per the `AGENTS.md` convention)
- A **Claude Code skill** wrapper (`.claude/skills/prism/SKILL.md`)
- A **Cursor rules** wrapper (`.cursor/rules/prism.mdc`)
- A **GitHub Copilot** wrapper (`.github/copilot-instructions.md` for ambient context + `.github/prompts/prism.prompt.md` as the actual `/prism` slash-command file)
- Direct usage in any other LLM (ChatGPT, Gemini, Grok, etc.) by pasting `PRISM-skill.md` into the chat with the instruction *"read this and apply it"*.

The wrappers are thin — under 30 lines each — and exist only to make the skill discoverable inside their host environment. The substance is here.

---

## 2. The state machine

A PRISM session is a finite walk through six states. Transitions are triggered by a sub-command or by the human's explicit decision.

```
IDLE ──/prism prepare──▶ BRIEFING ──/prism refract──▶ REFRACTING
                                                          │
                                                          │ /prism sync
                                                          ▼
                                       INSPECTING ◀──/prism inspect
                                            │
                                            │ /prism settle
                                            ▼
                                         SETTLED
                                            │
                                            │ /prism memorialize
                                            ▼
                                       MEMORIALIZED
```

| State | What it means | Allowed transitions |
|-------|---------------|---------------------|
| `IDLE` | No active session, or previous one closed | `→ BRIEFING` via `/prism prepare` |
| `BRIEFING` | Brief is being drafted; not yet sent to any external AI | `→ REFRACTING` via `/prism refract` |
| `REFRACTING` | Brief is out; awaiting reviewer responses (collected by the human, often async over hours) | `→ INSPECTING` via `/prism inspect` (after the human pastes responses back) |
| `INSPECTING` | Cross-validation of every claim against the codebase; scoring grid filled | `→ SETTLED` via `/prism settle` |
| `SETTLED` | Human has decided. Decision is captured but not yet engraved | `→ MEMORIALIZED` via `/prism memorialize` |
| `MEMORIALIZED` | ADR is written, immune memory updated, decision and code committed together | `→ IDLE` (session complete) |

**Rules:**

- Forbidden jumps (e.g. `BRIEFING → INSPECTING` directly) must produce a refusal: *"State machine violation: cannot skip REFRACTING. Run `/prism refract` first."*
- A `/prism sync` is allowed from any non-terminal state — it re-reads `PRISM-SESSION.md` and reconciles the LLM's understanding with what the human did off-channel (paste responses, edit the brief, change reviewer roster).
- The human can force a state with `/prism settle --state=<NAME>` if a session is recovered from a corrupted file. Use sparingly.

---

## 3. The Self-Correction Token

Every response you produce while a session is active **MUST** begin with a single-line header:

```
PRISM_STATUS: <STATE> | SESSION_ID: <NNN> | RULES_STRICT_MODE: ON
```

Where:
- `<STATE>` is the current machine state (IDLE, BRIEFING, REFRACTING, INSPECTING, SETTLED, MEMORIALIZED)
- `<NNN>` is the session identifier (3-digit zero-padded counter, see Section 5)
- `RULES_STRICT_MODE: ON` is constant — it is a self-imposed reminder that the 14 Golden Rules are non-negotiable for the duration of the session.

**Why this exists.** The token forces a self-check at the top of every reply: *"Am I still in the right state? Does the action I am about to propose match this state? Are the Golden Rules still active?"* It also lets the human (and any other LLM that picks up the session later) immediately see where you think you are.

If you ever produce a reply without the token while a session is active, the human is entitled to interrupt you and force a `/prism sync`.

---

## 4. The Refraction Package

The killer artefact of this skill. When the user runs `/prism refract`, you produce a **single, self-contained block** the human can copy-paste verbatim into each external LLM (Grok, Gemini, ChatGPT, Copilot, …) without modification.

The package has three sections:

### 4.1 System instruction (temporary)

A short paragraph telling the receiving LLM that it is acting as a PRISM reviewer, that it must respond without seeing other reviewers' answers, and that it must use its highest reasoning mode (Extended Thinking / Think / Deep Think).

### 4.2 The brief

The full brief drafted in `BRIEFING` state, copied verbatim. No paraphrase, no summary — same brief, no modifications. (Golden Rule applies: the brief is the constant; the AIs are the variables.)

### 4.3 Imposed response format

A fixed structure the reviewer must follow:

```
=== <REVIEWER_NAME> ===

## Recommendation
<one-paragraph headline>

## Scoring (1-10 per axis)
- Technical accuracy: <n>
- Feasibility: <n>
- Security / compliance: <n>
- Durability: <n>
- UX / DX impact: <n>

## Justification
<2-4 paragraphs>

## Hallucination self-flag
<list any claim you are uncertain about; say "none" if confident>

## Game-changer
<an approach no one has thought of, if applicable>
```

**Why imposed format?** Free-form responses are hard to compare. A fixed structure makes the Inspect step mechanical: same headers, same axes, same hallucination self-flag section. Reviewers who deviate get re-prompted.

---

## 5. PRISM-SESSION.md — the persistent state

Every session writes a single Markdown file at the project root: `PRISM-SESSION.md`. It is the source of truth for the machine state. Any LLM can pick up the session by reading this file.

**It is gitignored by default** — sessions contain working hypotheses, anonymised but still internal, and the public deliverable is the ADR, not the session log. To publish a sanitised version see Section 7 (`prism-publish`).

### 5.1 File format

```markdown
---
session_id: 001
state: REFRACTING
topic: Skill architecture (Phase 4)
opened: 2026-05-10T08:30:00Z
last_updated: 2026-05-10T11:42:00Z
reviewers:
  - name: Copilot
    submitted: true
  - name: Gemini
    submitted: true
  - name: Grok
    submitted: false
    note: paid mode only — skipped
lead_llm: Claude
---

## Brief
<full brief text — the same one sent in the Refraction Package>

## Reviewer responses
### === COPILOT ===
<verbatim>

### === GEMINI ===
<verbatim>

## Inspect notes
- Hallucinations detected:
  - …
- Convergences:
  - …
- Divergences:
  - …

## Scoring grid
| Axis | Option A | Option B | Option C | Option D |
|------|----------|----------|----------|----------|
| …    | …        | …        | …        | …        |

## Settle
- Decision: <text or "pending">
- Decided by: <human name>
- Decided at: <ISO timestamp>

## Memorialize
- ADR file: examples/adr-NNN-<slug>.md
- Immune memory updated: yes/no
```

### 5.2 Operating rules on the file

- **One session per file at any time.** When a session reaches `MEMORIALIZED`, archive the file as `PRISM-SESSION.archive/NNN-<slug>.md` (still gitignored) and create a fresh `PRISM-SESSION.md` only when the next `/prism prepare` fires.
- **Append, don't truncate.** Each transition appends to the relevant section. Never delete a reviewer response or a hallucination note — they are evidence.
- **The `last_updated` timestamp is mandatory.** It tells the next LLM how stale the file is.
- **`session_id` increments monotonically** across all PRISM sessions in this repo. Read the highest number from `PRISM-SESSION.archive/` to compute the next.
- **Privacy note.** Gitignored does not mean private. When `PRISM-SESSION.md` is read by an LLM during a session (`/prism sync`, `/prism settle`, `/prism memorialize`, or any state-aware no-arg `/prism`), its full content is sent to the configured backend (Anthropic for Claude Code, Cursor's backend, GitHub for Copilot, etc.) like any other read file — subject to that vendor's retention and training policy for your tier. Apply Golden Rule #9 to the session file as strictly as to the brief: no secrets, no PII, no confidential business information. The only sanctioned public export path remains `prism-publish` (Section 7), which anonymises before staging.

---

## 6. The seven commands

### 6.1 `/prism` (no argument)

State-aware entry point. Behaviour:

1. Read `PRISM-SESSION.md`. If absent, declare state `IDLE` and offer to start a new session (*"No active PRISM session. Run `/prism prepare` to open one."*).
2. If present, print the Self-Correction Token, summarise the current state in 3-5 lines, and propose the next action.
3. Never auto-advance. The human picks the next sub-command.

### 6.2 `/prism prepare`

State requirement: `IDLE` (or `MEMORIALIZED`, treated as IDLE).

Output:
- Compute next `session_id`
- Create `PRISM-SESSION.md` with `state: BRIEFING`
- Drive an interactive briefing using [templates/brief.md](templates/brief.md):
  - Technical context (stack, files, current architecture)
  - Problem to solve (what, why now, impact if unresolved)
  - Constraints (security, performance, compatibility, budget)
  - Identified options (mark as non-exhaustive)
  - Inventories (Docker containers, configs, touched files)
  - Open questions including the **game-changing prompt**
- Display the full brief in plain text and **WAIT** for the human to confirm. Do not advance until the human says GO. (Golden Rule #2.)

Reminder to enforce: **never include secrets** in the brief (Golden Rule #9). If the LLM detects an API key, password, or PII pattern, refuse and ask for redaction.

### 6.3 `/prism refract`

State requirement: `BRIEFING`.

Output:
- Generate the **Refraction Package** (Section 4) as a single fenced code block, ready to copy.
- Write `state: REFRACTING` to the session file.
- Print operational reminders:
  - *"Submit this verbatim to each reviewer independently. Do not show one reviewer's response to another."*
  - *"Use the highest reasoning mode available on each platform (Extended Thinking, Think Mode, Deep Think)."*
  - *"Label each response `=== <NAME> ===` when pasting back."*
- Then **stop**. The human now leaves the chat to consult external LLMs. They may return hours later — expect the session file to be the only continuity.

### 6.4 `/prism sync`

Allowed from any non-terminal state.

Use cases:
- The human pasted reviewer responses directly into the chat without using a sub-command — `/prism sync` reconciles them into `PRISM-SESSION.md`.
- The session file was edited by hand (e.g. reviewer roster changed) — re-read it and confirm the new state.
- A different LLM picks up the session — read the file, restate the state in plain English, ask the human to confirm before proceeding.

`sync` never advances state on its own. It only realigns the LLM's view with the file.

### 6.5 `/prism inspect`

State requirement: `REFRACTING` with at least 2 reviewer responses captured.

Output:
- For each claim in each reviewer response, cross-validate against the **real codebase** (not docs, not other reviewers). Use Read/Grep/Bash, not memory.
- Classify findings:
  - **Hallucinations** (Factual / Architectural / Context — see PRISM.md §Anti-Hallucination Protocol)
  - **Convergences** (independent agreement = strong signal)
  - **Divergences** (disagreement = often the most valuable signal)
  - **Valid insights** (an approach the others didn't see)
- Fill the **5-axis scoring grid** for every option (Technical accuracy, Feasibility, Security/compliance, Durability, UX/DX impact).
- Flag any axis where two reviewers diverge by 3+ points — propose a targeted second round if appropriate.
- Write everything into the `## Inspect notes` and `## Scoring grid` sections of `PRISM-SESSION.md`.
- Set `state: INSPECTING` on entry; do not auto-advance to SETTLED.

### 6.6 `/prism settle`

State requirement: `INSPECTING`.

Output:
- Present the synthesis to the human in 1 page max: top recommendation, dissents, scoring averages, hallucinations, divergences worth a second round.
- **Wait for human input.** The human chooses one of:
  - Follow the recommendation as-is
  - Modify the recommendation
  - Reject entirely
  - Request a second targeted (non-blind) round — this loops back to a partial REFRACTING with an exposure prompt: *"Reviewer X said A, Reviewer Y said B — analyse both and say which is more robust."*
- Capture the decision verbatim in the `## Settle` section.
- Set `state: SETTLED`.
- Do not implement anything. Implementation belongs in MEMORIALIZE only.

### 6.7 `/prism memorialize`

State requirement: `SETTLED`.

Output:
- Generate the ADR using [templates/adr.md](templates/adr.md):
  - File: `examples/adr-NNN-<slug>.md` (NNN matches `session_id`)
  - Decision, options considered, rejected alternatives with reasons, scoring grid, **detected hallucinations**, reviewer roster.
- Update `PRISM_MEMORY.md` with new hallucinations as immune-memory entries.
- Tell the human: *"ADR drafted. Review it before we commit. The ADR and the implementation should land in the same commit (Golden Rule #13)."*
- Set `state: MEMORIALIZED`.
- After human confirms commit, archive `PRISM-SESSION.md` to `PRISM-SESSION.archive/NNN-<slug>.md` and remove the live file. Next `/prism prepare` will create a new one.

---

## 7. `prism-publish` — anonymised session export

The session file is gitignored by design (it contains internal hypotheses, intermediate scoring, raw reviewer text). But sometimes the *journey* itself is the lesson — see ADR-007 (this skill's own genesis) which documents a self-referential PRISM session as an example.

`prism-publish` is the controlled escape hatch. When the human runs it, you:

1. Read the current `PRISM-SESSION.md` (or a named archive).
2. **Anonymise**:
   - Strip the `lead_llm` field if it identifies a paid product/account.
   - Replace any company-specific identifiers (employer name, internal codenames, customer names) with generic placeholders.
   - Redact file paths that leak directory structure beyond the repo (e.g. `/Users/<name>/projets/...` → `<repo-root>`).
   - Remove the `## Reviewer responses` section unless the reviewers' verbatim text is itself the lesson — in which case keep it but strip personal references.
3. Output to `examples/session-NNN-<slug>.md` with a top banner: *"Anonymised export of an internal PRISM session. The authoritative public deliverable is the corresponding ADR."*
4. Refuse to publish if the session is still `IDLE` / `BRIEFING` / `REFRACTING` (no synthesis yet — nothing to learn from).
5. Confirm with the human before staging the file for git.

The ADR remains the canonical public artefact. `prism-publish` is opt-in and rarely used.

---

## 8. Golden Rules — quick reference

The full text lives in [PRISM.md §The 14 Golden Rules](PRISM.md#the-14-golden-rules). Here is the operational summary you must keep active:

| # | Rule | When it bites you |
|---|------|-------------------|
| 1 | Free exchange, not a form | If you're tempted to ask "yes/no?" — stop |
| 2 | Display the full brief, then WAIT | After `/prism prepare` |
| 3 | The human says GO | Constantly. Never act without explicit GO. |
| 4 | Persist at every step | Every state transition writes to the session file |
| 5 | Never recycle | A previous brief is not a template — start fresh |
| 6 | Technical context header | Brief without context is rejected by reviewers |
| 7 | Options non-exhaustive | Always state this — reviewers can propose more |
| 8 | Include inventories | Reviewers without code access need them |
| 9 | Never include secrets | Refuse to advance if you spot any |
| 10 | Code is source of truth | Inspect against code, not against docs |
| 11 | Hallucinations are documented | Every detected one goes into the ADR |
| 12 | Synthesis persisted same round | Never defer the writeup |
| 13 | One ADR per decision | Resist mega-ADRs |
| 14 | Rejected ADRs documented | The "no" is as valuable as the "yes" |

---

## 9. What this skill is NOT

- **It is not a fully automated College.** It is a *guide rails* skill. The human is still the decision-maker, the reviewer pipeline is still manual (copy-paste between LLMs), and the session can take hours or days.
- **It is not Claude-specific.** The wrappers in `.claude/skills/` and `.cursor/rules/` are conveniences. The substance is in this file, which any LLM can read.
- **It is not an MCP server.** PRISM v1.x deliberately ships with zero runtime dependencies. An MCP variant is parked for v3 if demand materialises.
- **It is not a replacement for PRISM.md.** Read PRISM.md for the *why* and the *what*. Read this file for the *how to execute*.

---

## License

`PRISM-skill.md` is the *code* layer of the PRISM framework.

**License:** [Apache License 2.0](LICENSE-CODE)

**Copyright 2026 Jean-Marc Nahlovsky — The College of AI-rchitects**

The companion methodology file `PRISM.md` is licensed CC BY-SA 4.0 (see `LICENSE-METHOD`). The two licenses coexist by design: the method is share-alike to keep PRISM open; the execution code is permissive so wrappers and integrations can ship under any license downstream.