# How PAI Ideal State Criteria (ISC) Tracking Works in the THINK Phase

> Discover how PAI's Ideal State Criteria (ISC) tracking functions in the THINK phase. Learn about resolving dimensions, validating requirements, and ensuring concrete success criteria.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: internals
- Published: 2026-02-16

---

**During the THINK phase, PAI refines the Ideal State Criteria by resolving unknown dimensions through the `resolveDimension()` function, validating requirements against the refreshed ISC via the FormatReminder hook, and appending immutable updates to `IdealState.jsonl` to ensure downstream phases operate on concrete, testable success criteria.**

The Personal AI Infrastructure (PAI) by Daniel Miessler implements a rigorous seven-phase algorithm that treats the Ideal State Criteria (ISC) as a living document. During the THINK phase, the system transforms vague requirements into specific, verifiable dimensions that define what "done" looks like for any given task.

## What Is the Ideal State Criteria (ISC) in PAI?

The **Ideal State Criteria (ISC)** is a structured table that records every dimension of what "ideal" looks like for a given task. Each dimension includes a description, discovery type, and resolution status. The ISC begins as a minimal set of requirements during the OBSERVE phase and evolves into a comprehensive specification by the end of THINK.

## The Seven-Phase Algorithm and Where THINK Fits

PAI processes every task through a strict sequence: **OBSERVE → THINK → PLAN → BUILD → EXECUTE → VERIFY → LEARN**.

The **THINK** phase serves as the refinement loop for the ISC. While OBSERVE creates the initial work item with many dimensions marked as `unknown`, THINK resolves these ambiguities through systematic discovery and validation. Only after THINK completes does the algorithm proceed to PLAN with a fully-specified target state.

## How ISC Tracking Works During the THINK Phase

### Step 1: Discovery of Unknown Dimensions

When a task is first observed, PAI creates a minimal ISC with many dimensions still marked as `unknown`. In [`Releases/v2.3/.claude/hooks/lib/IdealState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.3/.claude/hooks/lib/IdealState.ts), the `appendStateUpdate` function records this initial state:

```typescript
// In IdealState.ts – initial creation (OBSERVE)
appendStateUpdate(
  workDir,
  'initial',
  'OBSERVE',
  initialState,
  `Work item created with ${dimCount} dimensions (${unknownCount} UNKNOWN)…`);

```

This creates the baseline that the THINK phase will refine.

### Step 2: Resolution via resolveDimension()

The THINK phase runs a *justify-exclusion* step that pulls all dimensions with `unknown` status using `getUnresolvedDimensions`. The main agent or a human provides concrete descriptions, which triggers the `resolveDimension` helper in [`IdealState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IdealState.ts).

This function performs four critical actions:

- Updates the dimension's `description` and marks it `resolved`
- Sets `resolved_in` to the current phase (normally `THINK`)
- Changes `discovery_type` to `INFERRED`
- Writes a `phase_feedback` entry to the ISC JSONL log

```typescript
export function resolveDimension(
  workDir: string,
  dimensionId: string,
  resolvedDescription: string
): void {
  const state = readIdealState(workDir);
  // ...
  const updatedDimensions = state.dimensions.map(d =>
    d.id === dimensionId
      ? { ...d,
          description: resolvedDescription,
          discovery_type: 'INFERRED',
          resolved_in: state.current_phase || 'THINK',
          status: 'resolved' }
      : d );
  appendStateUpdate(workDir, 'phase_feedback',
    state.current_phase || 'THINK', { dimensions: updatedDimensions },
    `Resolved dimension ${dimensionId}`);
}

```

### Step 3: Validation Against the Refreshed ISC

After resolution, the *FormatReminder* hook (Pass 2) in [`Releases/v2.5/.claude/hooks/FormatReminder.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.5/.claude/hooks/FormatReminder.hook.ts) validates the request against the refreshed ISC. It extracts thinking tools hints from the first pass, then requires the main agent to **justify** each hint by verifying the corresponding dimension exists and is no longer `unknown`.

```typescript
// FormatReminder.hook.ts – PASS 2 (THINK) validation
// "validate against reverse-engineered request + ISC"
// (the hook prints a reminder that the main agent must run a justification)

```

This ensures that THINK phase outputs align with the concrete criteria before proceeding to PLAN.

### Step 4: Immutable State Updates

Every resolution triggers `appendStateUpdate`, which writes a new line to `IdealState.jsonl`. This append-only log creates an immutable history that the VERIFY phase uses to compute gaps and the LEARN phase uses to evaluate fidelity against the original intent.

### Step 5: Outcome for Downstream Phases

By the end of THINK, the ISC contains only *resolved* dimensions, each linked to a concrete success criterion. The algorithm then proceeds to PLAN with a fully-specified target state, ensuring that BUILD and EXECUTE phases operate against testable requirements rather than ambiguous goals.

## Practical Code Example: Resolving Dimensions in THINK

The following TypeScript snippet demonstrates the complete workflow for ISC refinement during the THINK phase:

```typescript
// 1️⃣ Load the current work directory (auto-discovered)
import { findActiveWorkDir, resolveDimension, getUnresolvedDimensions } from './IdealState';

const workDir = findActiveWorkDir()!;
if (!workDir) throw new Error('No active work');

// 2️⃣ List dimensions that still need thinking (THINK phase)
const unknown = getUnresolvedDimensions(workDir);
console.log('🔎 Unresolved dimensions:', unknown.map(d => d.id));

// 3️⃣ Resolve one of them (normally done after the agent asks a clarifying question)
resolveDimension(workDir, 'DIM-FUNC-3', 'The UI must support dark mode toggle');

// 4️⃣ Verify that the ISC file grew a new entry
import { readFileSync } from 'fs';
const iscLog = readFileSync(`${workDir}/IdealState.jsonl`, 'utf-8')
  .trim()
  .split('\n')
  .pop();               // newest line
console.log('📝 Latest ISC entry:', iscLog);

```

Running this snippet in a PAI session shows the unknown dimensions, resolves one, and prints the newly-appended JSONL line, demonstrating the immutable logging mechanism.

## Key Files Involved in ISC Tracking

| File | Role in ISC tracking (THINK) |
|------|------------------------------|
| [`Releases/v2.3/.claude/hooks/lib/IdealState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.3/.claude/hooks/lib/IdealState.ts) | Core utilities: `addDimension`, `resolveDimension`, `getUnresolvedDimensions`, immutable `appendStateUpdate` log. |
| [`Releases/v2.5/.claude/hooks/FormatReminder.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.5/.claude/hooks/FormatReminder.hook.ts) | Pass 2 (THINK) reminder that the main agent must validate the request against the refreshed ISC. |
| [`Releases/v2.3/.claude/hooks/AutoWorkCreation.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.3/.claude/hooks/AutoWorkCreation.hook.ts) | Creates the work directory with [`IDEAL.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IDEAL.md) placeholder and `IdealState.jsonl` ready for THINK updates. |
| [`Releases/v2.3/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v2.3/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts) | Visualises the current phase (including THINK) for the user, helping them see ISC progress. |

These files together implement the *think-time* refinement of the Ideal State Criteria, ensuring that every later phase works against a concrete, verifiable definition of "done".

## Summary

- The **THINK** phase serves as the refinement loop for PAI's Ideal State Criteria, transforming ambiguous `unknown` dimensions into concrete, testable requirements.
- **Resolution** occurs through the `resolveDimension()` function in [`IdealState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IdealState.ts), which updates dimension descriptions, marks them as `resolved`, and sets `resolved_in` to `THINK`.
- **Validation** happens via the [`FormatReminder.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/FormatReminder.hook.ts) Pass 2 check, ensuring the main agent justifies all thinking tools against the refreshed ISC before proceeding to PLAN.
- **Immutable logging** via `appendStateUpdate()` writes every change to `IdealState.jsonl`, creating an audit trail for VERIFY and LEARN phases.
- By the end of THINK, the ISC contains only resolved dimensions, ensuring BUILD and EXECUTE phases operate against fully-specified success criteria.

## Frequently Asked Questions

### How does PAI distinguish between OBSERVE and THINK phase ISC updates?

During **OBSERVE**, PAI creates the initial ISC with dimensions often marked as `unknown` using `appendStateUpdate` with the phase label `OBSERVE`. During **THINK**, the system calls `resolveDimension()`, which explicitly sets `resolved_in: 'THINK'` and writes a `phase_feedback` entry to the JSONL log. This phase attribution creates a clear audit trail showing when each dimension transitioned from ambiguous to concrete.

### What happens if dimensions remain unresolved after the THINK phase?

The THINK phase is designed to resolve all `unknown` dimensions before proceeding to PLAN. If dimensions remain unresolved, the [`FormatReminder.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/FormatReminder.hook.ts) validation in Pass 2 will flag the discrepancy during the justification step, preventing the algorithm from advancing. The system requires explicit resolution via `resolveDimension()` to ensure downstream phases do not operate against incomplete criteria.

### How does the immutable JSONL logging support later phases?

Every call to `appendStateUpdate()` appends a new line to `IdealState.jsonl` rather than modifying existing entries. During **VERIFY**, the system reads this log to compute gaps between the actual output and the resolved ISC. During **LEARN**, the algorithm evaluates fidelity by comparing the final state against the historical progression recorded in the JSONL, enabling continuous improvement of the dimension discovery process.

### Can human operators manually trigger dimension resolution during THINK?

Yes. While the main agent typically drives the process, the `resolveDimension()` function in [`IdealState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IdealState.ts) accepts manual input via the `resolvedDescription` parameter. Human operators can review the list of `unknown` dimensions retrieved by `getUnresolvedDimensions()`, provide concrete descriptions for ambiguous criteria, and call `resolveDimension()` to update the ISC with human-validated requirements before the algorithm proceeds to PLAN.