# Cognitive Operating System

This document describes the thinking model this template is designed to make repeatable.

The goal is not to make agents verbose. The goal is to make the important parts of engineering judgment visible, reviewable, and reusable.

## Core Loop

Every non-trivial task should move through five states:

1. Frame the work.
2. Inspect the real repository state.
3. Choose the smallest correct change.
4. Verify with the narrowest reliable check.
5. Leave a useful artifact for the next worker.

The artifact may be a code change, a test, a decision record, a research brief, a review, or a handoff.

## R&D Mode

Use R&D mode when the answer is not known yet.

R&D work optimizes for learning speed and evidence quality.

Required posture:

- state the hypothesis
- list the evidence inspected
- distinguish confirmed facts from inference
- keep experiments reversible
- record confidence and next experiment

Good R&D output makes the next decision cheaper.

Use the `research-brief` skill when the task is primarily about discovery.

## Production Mode

Use production mode when the system behavior, contract, or user experience is being changed.

Production work optimizes for correctness, small blast radius, and verification.

Required posture:

- identify affected surfaces
- keep diffs narrow
- preserve existing ownership boundaries
- run focused verification before broad gates
- document rollout and rollback conditions when relevant

Use the `production-change` skill when the task changes durable behavior.

## Decision Discipline

A decision deserves a record when:

- multiple reasonable options exist
- the choice affects future work
- the change alters the template contract
- the team may need to reverse or audit the reasoning later

Use the `decision-record` skill for these cases.

## Delegation Discipline

Delegate only when parallel work will improve the outcome.

Good delegation has:

- a bounded scope
- a clear write or read responsibility
- non-overlapping ownership
- a concrete expected output
- a verification expectation

Do not delegate the immediate blocking task if the main worker can resolve it faster locally.

## Review Discipline

Review is a defect-finding activity first.

A useful review:

- leads with findings
- cites files or behavior
- prioritizes correctness, regressions, safety, and missing tests
- separates confirmed issues from suggestions
- says clearly when no material issue was found

Use the `review-request` skill when asking for this posture.

## Handoff Discipline

A handoff should remove ambiguity for the next worker.

It should include:

- what changed
- files or responsibility owned
- verification already run
- remaining risks, blockers, or assumptions
- next highest-value check

Use the `handoff` skill when ownership changes.

## Failure Analysis

Use incident analysis when a defect, safety issue, failed rollout, or broken verification path exposes a system weakness.

The goal is to improve the operating system, not to assign blame.

Use the `incident-analysis` skill to capture timeline, root cause, contributing factors, and prevention work.

## Operating Modes Summary

```text
Unknown answer       -> research-brief
Durable change       -> production-change
Important tradeoff   -> decision-record
Regression or outage -> incident-analysis
Ownership transfer   -> handoff
Defect finding       -> review-request
Task start           -> task-kickoff
```

## Quality Bar

The strongest agent sessions leave behind enough evidence that another engineer can understand:

- what the task was
- what context mattered
- what changed
- why this approach was chosen
- how it was verified
- what risk remains