pqrst-practice/history/20260905-PqrstEstimationPractice_chatgpt.md

# PQRST Estimation Practice

## Purpose

PQRST is a lightweight retrospective audit for agentic coding sessions.

It answers:

> **Where did the effective engineering effort of this session actually go?**

PQRST is **not a planning tool, target allocation, productivity score, or precise accounting method**. It is a structured post-session estimate intended to make the character of a coding session visible and comparable over time.

The value of PQRST lies less in the exact percentages than in the combination of:

1. a forced 100% allocation;
2. stable categories across sessions;
3. concise evidence-based rationales; and
4. trends observed across repeated work on the same codebase, project, agent, or task class.

---

## The PQRST Dimensions

### P — Main Problem

Effort spent directly producing the primary requested outcome.

Examples:

- implementing the feature or fix;
- changing application logic;
- writing the algorithm;
- creating the requested integration;
- resolving the main defect;
- producing the principal deliverable.

P should represent **direct progress on the core task**, not all work that happened to be necessary during the session.

---

### Q — Quality and Tests

Effort spent establishing confidence that the result is correct, robust, maintainable, and fit to keep.

Examples:

- unit, integration, end-to-end, regression, or property tests;
- test fixtures and test infrastructure used for verification;
- edge-case handling;
- validation and error handling;
- debugging performed primarily to establish correctness;
- refactoring for maintainability after the main behavior works;
- static analysis, linting, type checking, and verification;
- reviewing the implementation for correctness or structural quality.

Q is deliberately separated from P because **making something work is different from establishing that it works well enough to retain**.

---

### R — Research and Context Clarification

Effort spent understanding what the task, codebase, system, dependency, or requirement actually means before or while deciding what to change.

Examples:

- reading repository files to reconstruct architecture or behavior;
- tracing call graphs, data flows, or configuration;
- reading external documentation or specifications;
- inspecting existing tests to infer intended behavior;
- resolving conflicting comments or implementations;
- investigating unfamiliar APIs or libraries;
- clarifying requirements or ambiguous task boundaries;
- determining why the current system behaves as it does.

High R is often healthy in unfamiliar territory. Persistently high R in repeated work may indicate weak documentation, insufficient context, unstable architecture, or poor task framing.

---

### S — Security and Credentials

Effort spent specifically on security-relevant constraints, identity, permissions, credentials, secrets, trust boundaries, abuse resistance, or protection of sensitive data.

Examples:

- authentication and authorization analysis;
- handling secrets, tokens, certificates, or credentials;
- access-control configuration;
- tenant-isolation checks;
- security review of user-controlled input;
- threat-oriented reasoning;
- permission troubleshooting;
- credential acquisition, renewal, storage, or safe use;
- remediation of security-specific findings.

S may legitimately be **0%** for many sessions. Do not inflate S merely because secure engineering is generally desirable. Assign effort to S only when security-specific work actually occurred.

---

### T — Task Organization

Effort spent structuring, sequencing, tracking, and coordinating the work rather than directly solving or validating the technical problem.

Examples:

- decomposing the task into steps;
- planning implementation order;
- maintaining todo lists or milestone state;
- deciding which files or subsystems to address first;
- organizing intermediate artifacts;
- coordinating parallel or delegated work;
- recovering from a poor task sequence;
- repeated replanning caused by scope drift or thrashing.

Some T is productive coordination. Excessive or repeated T may signal unstable scope, weak decomposition, or agent workflow inefficiency.

---

## Estimation Rules

### 1. Estimate retrospectively

Generate PQRST **only after the substantive session work is complete**. Do not use a desired PQRST profile as a target for planning the session.

### 2. Allocate exactly 100%

The five values MUST sum to exactly **100%**.

### 3. Estimate effective engineering effort, not telemetry

The estimate should represent the relative share of **meaningful engineering attention and work** observed during the session.

It is not a reconstruction of:

- wall-clock time;
- token usage;
- number of tool calls;
- CPU or compute consumption;
- human review time; or
- any hidden internal model process.

The percentages are a **semantic retrospective estimate**, not instrumented measurement.

### 4. Ground every category in observable session activity

Each non-zero percentage should be justified using concrete evidence from the session where possible, such as:

- files or modules inspected or changed;
- tests written or executed;
- documentation or external sources consulted;
- credentials, permissions, or security boundaries handled;
- plans, task lists, decomposition, or coordination performed.

Avoid generic rationales such as "some testing was done" when more concrete evidence is available.

### 5. Attribute overlapping work by primary purpose

PQRST categories inevitably overlap. When an activity could fit several categories, assign its effort according to the **primary reason the activity was undertaken at that moment**.

Examples:

- Reading a module to understand how it works → **R**.
- Editing that module to implement the requested feature → **P**.
- Writing a test to prove the feature works → **Q**.
- Writing a test mainly to discover undocumented behavior → **R**.
- Changing authorization logic because the requested feature requires it → split between **P** and **S** according to how much work was feature implementation versus security-specific reasoning and control.
- Repeatedly reorganizing the work after losing track of scope → **T**.

Do not double-count the same effort across categories.

### 6. Do not optimize for a "good" profile

There is no universally correct PQRST distribution.

A healthy exploratory session may be R-heavy. A stabilization session may be Q-heavy. A credential integration may be S-heavy. A straightforward implementation may be P-heavy.

The purpose is to describe the session faithfully, not to maximize P or minimize the other categories.

### 7. Prefer coarse honesty over theatrical precision

Percentages should normally be estimated in increments of approximately **5 percentage points** unless the distribution is unusually clear.

`35%` is usually more credible and useful than `33.7%`.

### 8. Include zero values explicitly

Always report all five dimensions, including legitimate zeroes. A zero is information.

---

## Canonical End-of-Session Prompt

Use the following prompt after the substantive coding session has concluded:

```text
Please produce a retrospective PQRST Estimate for this completed coding session.

Estimate how the session's effective engineering effort was distributed across exactly these five dimensions:

P — Main Problem: direct work producing the primary requested outcome, such as implementing the feature, fix, algorithm, integration, or other core deliverable.

Q — Quality and Tests: work establishing correctness, robustness, maintainability, and confidence, including tests, verification, edge cases, debugging for correctness, validation, error handling, and quality-oriented refactoring.

R — Research and Context Clarification: work required to understand the task, repository, architecture, dependencies, existing behavior, documentation, specifications, or ambiguous requirements.

S — Security and Credentials: security-specific work involving authentication, authorization, permissions, credentials, secrets, tenant isolation, trust boundaries, sensitive data, threat considerations, or security controls. S may legitimately be 0% and must not be inflated merely because security is generally important.

T — Task Organization: planning, decomposition, sequencing, todo management, coordination, scope management, and other effort spent keeping the work organized rather than directly implementing or validating it.

Rules:

1. Treat this strictly as a retrospective audit, not as a planning target or productivity score.
2. Allocate exactly 100% across P, Q, R, S, and T.
3. Estimate relative effective engineering effort, not tokens, tool calls, wall-clock time, compute, or hidden model activity.
4. Where categories overlap, classify effort by the primary purpose of the activity at the time and do not double-count it.
5. Ground each non-zero category in concrete evidence from what actually happened in this session: files/modules inspected or changed, tests performed, documentation researched, security/credential work handled, or planning/coordination performed.
6. Do not force every category to be non-zero.
7. Prefer honest coarse estimates, normally in roughly 5 percentage-point increments, over false precision.
8. After the percentages, give one concise evidence-based rationale for each category and one short overall interpretation of the session profile.
9. If the session record is insufficient to estimate a category confidently, say so rather than inventing evidence.

Return the result using the canonical PQRST Result Format below.
```

---

## Canonical PQRST Result Format

```markdown
## PQRST Estimate

| Dimension | Estimate | Evidence / rationale |
|---|---:|---|
| P — Main Problem | NN% | One concise statement grounded in the main implementation work actually performed. |
| Q — Quality and Tests | NN% | One concise statement grounded in tests, verification, debugging, robustness, or quality work actually performed. |
| R — Research and Context Clarification | NN% | One concise statement grounded in repository exploration, documentation, tracing, investigation, or requirement clarification actually performed. |
| S — Security and Credentials | NN% | One concise statement grounded in security, permissions, credentials, secrets, isolation, or security-control work actually performed; use 0% when none occurred. |
| T — Task Organization | NN% | One concise statement grounded in planning, decomposition, sequencing, coordination, or scope-management work actually performed. |
| **Total** | **100%** | |

**Session profile:** One sentence characterizing the session, for example: implementation-heavy, exploration-heavy, hardening-heavy, security-heavy, or coordination-heavy, including the principal reason.

**Estimate confidence:** High / Medium / Low — one short reason based on how observable and distinguishable the session activities were.
```

---

## Compact Machine-Friendly Form

When PQRST results are intended for collection across many sessions, append this optional block after the human-readable result:

```yaml
pqrst:
  p: NN
  q: NN
  r: NN
  s: NN
  t: NN
  total: 100
  profile: implementation-heavy | quality-heavy | exploration-heavy | security-heavy | coordination-heavy | mixed
  confidence: high | medium | low
```

The numeric values represent percentages and SHOULD be stored as integers unless a specific implementation has a strong reason to preserve finer granularity.

---

## Interpretation Guidance

PQRST is most useful as a **trend signal**, not as an isolated score.

Potential recurring patterns include:

| Pattern | Possible interpretation |
|---|---|
| High P, very low Q | Fast implementation with limited verification; possible quality debt. |
| High Q | Stabilization, hardening, debugging, or test-oriented work. |
| High R on first sessions | Normal exploration of an unfamiliar system. |
| Persistently high R on repeated sessions | Weak documentation, insufficient context, architectural opacity, unstable requirements, or poor task framing. |
| Falling R over repeated work | Growing repository familiarity or improving contextual support. |
| High S | Security-sensitive task, credential friction, permission complexity, or substantial trust-boundary work. |
| Unexpectedly zero S on security-relevant work | Possible missing security attention; warrants qualitative review rather than automatic judgment. |
| High T | Significant coordination/decomposition burden; may be healthy for complex work or may indicate workflow thrashing. |
| Falling T over repeated similar sessions | Better task framing, stronger working context, or improved agent workflow. |
| Rising Q as a project matures | Possible transition from implementation toward stabilization and production readiness. |

These interpretations are hypotheses for review, not automatic conclusions.

---

## Recommended Practice

1. Generate one PQRST Estimate at the **end of a substantive agentic coding session**.
2. Store the estimate together with enough session metadata to identify the repository, task, date, and optionally agent/model or workflow used.
3. Preserve the rationales, not only the percentages.
4. Review distributions over multiple sessions rather than optimizing individual sessions toward a preferred profile.
5. Investigate surprising changes or persistent patterns qualitatively.
6. Do not rank developers, agents, or teams using raw PQRST percentages without additional outcome evidence.
7. Correlate PQRST with external outcomes where useful, such as task completion, defects, test results, rework, cost, interventions, or later reversions.

---

## Design Principle

> **PQRST should make the session more legible without making the session perform for the metric.**

Its purpose is to expose whether the work was primarily spent solving the problem, establishing quality, understanding context, handling security, or organizing the task — and to preserve enough evidence to make that estimate useful later.