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

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, the appendStateUpdate function records this initial state:

// 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.

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

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 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.

// 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:

// 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	Core utilities: addDimension, resolveDimension, getUnresolvedDimensions, immutable appendStateUpdate log.
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	Creates the work directory with IDEAL.md placeholder and IdealState.jsonl ready for THINK updates.
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, which updates dimension descriptions, marks them as resolved, and sets resolved_in to THINK.
• Validation happens via the 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}