# 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 logical analysis
- Produces a structured `state_diff`

A state consists of:

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

Nothing mutates in place.
Progress is measured by **diffs and coverage**, not by edits.

---

## 3. The Agent Loop (Golden Path)

Every successful interaction follows this loop:

1. **Inspect**
   ```bash
   speclogician view state
   speclogician view diff
   ```

2. **Diagnose**
   - Missing predicates?
   - Inconsistent scenarios?
   - Large complement?
   - Traces not matching scenarios?

3. **Search**
   ```bash
   speclogician find predicates <query>
   speclogician find transitions <query>
   speclogician find artifacts <query>
   ```

4. **Apply exactly ONE change**
   ```bash
   speclogician ch ...
   ```

5. **Re‑inspect**
   ```bash
   speclogician view diff
   ```

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 is gated on base validity

---

### 4.2 Predicates

Predicates define **classifications**, not behavior.

```bash
speclogician ch pred-add   --pred-type STATE   --pred-name is_large_trade   --pred-src "s.amount > 1_000_000"
```

Types:
- STATE: properties of state
- ACTION: properties of actions

---

### 4.3 Transitions

Transitions define **state evolution**.

```bash
speclogician ch trans-add   --trans-name execute   --trans-src "let execute (s:state) (a:action) = { amount = s.amount + a }"
```

---

### 4.4 Scenarios

Scenarios define **intended behaviors**.

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

Scenarios:
- Are partial specifications
- Do not need to be complete
- Drive complement reasoning

---

### 4.5 Traces

Traces are **concrete evidence**.

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

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

---

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

Most important commands:

```bash
speclogician view diff
speclogician view spec
speclogician view domain
speclogician view artifacts
```

Rules:
- Always inspect `view diff`
- Treat diffs as first‑class artifacts
- Never assume success without checking

---

## 6. Search Commands (`speclogician find`)

Use search before modification.

```bash
speclogician find predicates limit --kind state
speclogician find transitions approve
speclogician find artifacts margin --kind docs
```

Search prevents duplicate logic and drift.

---

## 7. Complement & Coverage

The **scenario complement** represents:
> All logically possible behaviors not covered by scenarios.

Properties:
- Computed via ImandraX
- Semantic (not test‑based)
- Shrinking complement = progress

Signals:
- No complement → base or scenarios invalid
- Large complement → missing intent
- Empty complement → specification is complete (rare, valuable)

---

## 8. Worked Example 1: Minimal State Machine

### Goal
Model a simple counter with increment.

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

**Predicate**
```bash
speclogician ch pred-add --pred-type STATE --pred-name nonneg --pred-src "s.x >= 0"
```

**Transition**
```bash
speclogician ch trans-add --trans-name inc --trans-src "let inc s a = { x = s.x + a }"
```

**Scenario**
```bash
speclogician ch scenario-add inc_ok --given nonneg --then inc
```

Inspect:
```bash
speclogician view diff
```

Complement highlights:
- What about negative actions?
- What about overflow?

Add scenarios accordingly.

---

## 9. Worked Example 2: Financial Rule

### Rule
Large trades require approval.

**Predicate**
```bash
speclogician ch pred-add --pred-type STATE --pred-name large_trade --pred-src "s.amount > 1_000_000"
```

**Scenario**
```bash
speclogician ch scenario-add approval_required --given large_trade --then approve
```

Complement reveals:
- Small trades?
- Large trades without approval?
- Conflicting predicates?

This is logic discovery, not testing.

---

## 10. Domains Beyond Code

This workflow applies unchanged to:

- M&A contracts (conditions, obligations, breaches)
- Financial models (risk regions, limits)
- Regulatory logic (must/must-not rules)
- Protocols (valid/invalid sequences)

Replace:
- state → contract state
- action → event
- transition → clause effect

---

## 11. What NOT To Do

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

---

## 12. Final Agent Instructions

You are a **reasoning engine supervisor**.

Every step must:
- Be justified by `view` or `find`
- Produce a measurable `state_diff`
- Reduce inconsistency or complement
- Increase confidence and auditability

If unsure:
- Inspect more
- Ask for clarification
- Apply the smallest possible change

Formal reasoning is a process, not a jump.
