# SpecLogician Agent Playbook

## Formal Reasoning Copilot for Code, Finance, and Contracts

---

## 1. Purpose and Audience

This playbook is written for **LLM-based coding and reasoning agents** (Claude Code, Copilot, Cursor, internal agents) operating alongside:

- **SpecLogician** (stateful specification + analysis loop)
- **CodeLogician** (code → formal model translation)
- **ImandraX** (symbolic reasoning, decomposition, complement analysis)

The goal is to enable **trustworthy, auditable, and logically complete workflows** for regulated and high-assurance domains:

- Software systems
- Financial models
- Risk engines
- M&A and regulatory contracts
- Protocols and workflows

You are not a text editor. You are a **formal reasoning copilot**.

---

## 2. Core Mental Model

SpecLogician maintains an **immutable state history**.

Each change:

- Produces a new `StateInstance`
- Triggers exact logical analysis (ImandraX-backed)
- Updates coverage, conflicts, and reachability (when enabled/computed)
- Produces a structured `state_diff`

A state consists of:

```
State
 ├─ Spec
 │   ├─ Domain Model
 │   │   ├─ Base (types + invariants, IML)
 │   │   ├─ State Predicates
 │   │   ├─ Action Predicates
 │   │   └─ Transitions
 │   ├─ Scenarios (Given / When / Then, + is_initial)
 │   ├─ Scenario Complement (coverage)
 │   └─ Scenario Reachability Graph (stored on spec when computed)
 ├─ Artifact Container
 │   ├─ Test Traces
 │   ├─ Log Traces
 │   ├─ Documents
 │   └─ Source References
 ├─ Derived Stats
 └─ StateDiff (vs previous state)
```

Nothing mutates in place. Progress is measured by **semantic diffs, reachability, and coverage**, not by editing files.

---

## 3. The Agent Loop (Golden Path)

Every successful interaction follows this loop:

1. **Inspect**

   ```bash
   speclogician view state
   speclogician view diff
   ```

2. **Diagnose**

   - Invalid base?
   - Missing predicates or transitions?
   - Inconsistent or unreachable scenarios?
   - Large behavioral complement?
   - Traces failing validity or not matching scenarios?

3. **Search**

   ```bash
   speclogician find predicates <query> --kind all|state|action
   speclogician find transitions <query>
   speclogician find artifacts <query> --kind all|tests|logs|docs|src
   ```

4. **Apply exactly ONE change**

   ```bash
   speclogician ch ...
   ```

5. **Re-inspect**

   ```bash
   speclogician view diff
   speclogician reach summary --json
   ```

6. **Repeat**

> One change. One diff. One improvement.

---

## 4. Change Commands (`speclogician ch`)

### 4.1 Domain Base

Defines the semantic universe.

```bash
speclogician ch base-edit --src "type state = { x:int }
type action = int"
```

Rules:

- Must be valid IML
- Breaks everything downstream if wrong
- Complement and reachability depend on base validity

---

### 4.2 Predicates

Predicates define **classifications**, not behavior.

```bash
speclogician ch pred-add --pred-type state --pred-name large_trade --pred-src "s.amount > 1_000_000"
speclogician ch pred-add --pred-type action --pred-name is_buy --pred-src "a.side = BUY"
```

---

### 4.3 Transitions

Transitions define **state evolution**.

```bash
speclogician ch trans-add --trans-name execute --trans-src "{ amount = s.amount + a }"
```

---

### 4.4 Scenarios (Intent)

Scenarios encode **intended behavior**.

```bash
speclogician ch scenario-add trade_exec --given authorized --when place_order --then execute
```

Initial scenarios define reachability roots:

```bash
speclogician ch scenario-add boot --given initial_state --then init --initial
```

Rules:

- Scenarios are partial specifications
- They need not cover all behaviors
- Reachability queries rely on the stored graph (compute must have been run / enabled)

---

### 4.5 Traces (Evidence)

Traces provide **concrete examples**, not logic.

```bash
speclogician ch test-add \
  --art-id T1 \
  --name test_large_trade \
  --given "{ amount = 2_000_000 }" \
  --when "{ side = BUY }" \
  --then "{ approved = true }"
```

Traces validate intent but do **not replace scenarios**.

---

## 5. View Commands (`speclogician view`)

### 5.1 State (latest instance)

`view state` always shows the **latest** `StateInstance` (no `--idx`).

```bash
speclogician view state
speclogician view state --json
```

---

### 5.2 Trace Reachability (derived analysis, optional)

If the instance has `trace_reachability`, you can view it:

```bash
speclogician view trace-reachability --json
```

Filter to a single trace id:

```bash
speclogician view trace-reachability --trace <trace_id> --json
```

Behavioral expectation:
- Unknown `--trace` id ⇒ **empty trace list** in the PM (but summary/counts may still reflect the global analysis).

---

## 6. Reachability Commands (`speclogician reach`)

These commands query the stored `spec.scenario_reachability` graph.

If the graph is not computed yet, commands emit:

- JSON mode: `{ "ok": false, "notes": "Scenario reachability not computed" }`
- Rich mode: a hint telling you to run `speclogician reach compute`
- Then exit (no crash)

### 6.1 Summary

```bash
speclogician reach summary --json
```

Returns:

- Node and edge counts
- `initials`
- `reachable_from_initials`
- `unreachable`

---

### 6.2 Unreachable Scenarios

```bash
speclogician reach unreachable --json
```

Use to identify:

- Dead intent
- Missing transitions
- Over-constrained predicates

---

### 6.3 Local Navigation

```bash
speclogician reach succ <scenario>
speclogician reach pred <scenario>
```

---

### 6.4 Explainability

```bash
speclogician reach explain-edge <src> <dst> --json
speclogician reach explain-edge <src> <dst> --no-witness --json
```

Provides:

- Reachability verdict
- Notes about why not reachable (if applicable)
- Optional symbolic witness payload (unless `--no-witness`)

---

### 6.5 Paths

```bash
speclogician reach path <src> <dst> --json
```

Returns the shortest semantic path between scenarios (or empty/null if none).

---

### 6.6 Frontier Analysis

```bash
speclogician reach frontier --json
```

Frontier gaps highlight:

- Scenarios with missing outgoing edges
- Scenarios that “terminate” without modeled successors

These are **high-value refinement targets**.

---

## 7. Complement & Coverage

The **scenario complement** represents:

> All logically possible behaviors not yet explained by any scenario.

Properties:

- Computed symbolically via ImandraX
- Semantic, not test-based
- Shrinking complement = progress

Signals:

- No complement → invalid base or scenarios (or complement not computed)
- Large complement → missing intent
- Empty complement → logically complete specification

---

## 8. What NOT To Do

❌ Edit files directly  
❌ Apply multiple changes at once  
❌ Ignore `state_diff`  
❌ Confuse tests with coverage  
❌ Assume intuition equals correctness  

---

## 9. Final Agent Instructions

You are a **formal reasoning supervisor**.

Every step must:

- Be justified by `view`, `find`, or `reach`
- Produce a measurable `state_diff`
- Reduce inconsistency or complement
- Improve reachability structure
- Increase auditability and explainability

If unsure:

- Inspect more
- Apply the smallest possible change
- Re-check:

  ```bash
  speclogician reach summary --json
  ```

Formal reasoning is a process, not a jump.
