coulomb/pqrst-practice
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Consolidate PQRST drafts into spec v0.1; add prompt, intent, scope

Browse source 
Merge the two independent 2026-09-05 drafts under history/ into a single
normative specification at spec/PqrstEstimationPractice.md (v0.1).

Where the sources diverged on the canonical result format, the block/
signature record is adopted as the source of truth and the per-dimension
table is retained as an optional presentation form; recorded in the spec's
version history. Two rules the sources implied but did not state are added:
confidence stays outside the 5-tuple (R9), and no sixth dimension may be
introduced (R10).

Add PqrstPrompt.md in the root as the canonical end-of-session prompt,
pairing the fuller rule list with the strict fixed output block.

Add INTENT.md and SCOPE.md framing the repo as the means of closing
agentic coding sessions: why the practice exists, its anti-goals, and the
boundary that this is a specification-and-prompt repo only — no tooling,
storage, harness integration, scoring, or empirical validation.

Source drafts under history/ are retained unmodified and are append-only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ6oF1DtVDKcD1FCpvRVLx

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 272883@bnt-lap001
Assistant-Session: f40c8f53-fb65-4980-9d29-bcdb3dd946f7
This commit is contained in:
tegwick 2026-09-05 20:27:36 +02:00
parent c6723a6aca
commit 4986a87773
6 changed files with 1237 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

49
INTENT.md Normal file
View file

@ -0,0 +1,49 @@
# Intent
## Why this repository exists
Agentic coding sessions end without a closing move. Work stops when the task is done, the context window fills, or attention moves elsewhere. What the session *was* — where the engineering attention actually went — evaporates with the transcript.
This repository provides the means of **closing an agentic coding session**: a short, standard, retrospective act performed at the end of a bounded unit of work, producing one durable, comparable record.
The instrument is PQRST — a forced 100% allocation of the session's effective engineering effort across five stable dimensions: **P**roblem, **Q**uality, **R**esearch, **S**ecurity, **T**ask organization.
## The problem being addressed
An individual session is legible while you are in it and opaque a week later. Across many sessions the questions that matter are process questions, and none of them can be answered from transcripts:
- Is research effort on this repository falling as its documentation improves, or not?
- Do sessions that spend more effort coordinating than building fail more often, or merely cost more?
- Are we shipping implementation with no verification behind it, and paying for that in later bugfix sessions?
- Does security work appear where the task class says it should?
Existing telemetry — tokens, wall-clock time, tool-call counts, diff size — measures consumption, not character. A session can burn a large budget on reconstructing an undocumented request path and produce three lines of code; another can spend the same budget implementing a well-specified feature. Consumption metrics cannot tell those apart. **PQRST is a judgment, deliberately, because the thing worth recording is a judgment.**
## What we intend PQRST to be
A **lens**, applied consistently, whose value accumulates in aggregate.
1. **Retrospective, never prospective.** The estimate is produced after the work. A session must never be steered toward a target signature. The moment PQRST becomes something to hit, it stops describing anything.
2. **Coarse and honest.** Five-point increments and a stated confidence beat invented precision. A defensible `P30 Q20 R30 S0 T20` at low confidence is worth more than a fabricated `P31 Q19 R28 S2 T20`.
3. **Auditable.** A signature without its dominant-factors sentence is not a record. Numbers are the index; the evidence is the content.
4. **Stable.** The five dimensions do not change, so that records made a year apart remain comparable. Detail is added by expanding a letter into subdimensions, never by growing the acronym.
5. **Diagnostic, not evaluative.** There is no good profile. An exploration session is R-heavy; a hardening session is Q-heavy; a credential integration is S-heavy. The question is always whether the mix fits the class of task.
## What we intend it not to become
- **Not a productivity score.** PQRST does not rank developers, agents, models, or teams. Raw percentages carry no verdict, and using them as one destroys the honesty the practice depends on.
- **Not telemetry.** It does not reconstruct time, tokens, compute, or tool calls. Cost measures may be stored *alongside* a record; they may never substitute for one.
- **Not a planning tool.** No session is designed against a PQRST budget.
- **Not a completeness ritual.** A zero is information. A dimension inflated so the record "looks thorough" poisons every trend it enters.
## The measure of success
This repository succeeds when a session can be closed in under a minute; when the resulting record is still meaningful six months later; and when accumulated records change something real — a document that gets written because research effort refused to fall, a workflow that gets fixed because coordination effort kept dominating routine changes.
It fails the moment anyone tries to score well on it.
## Related documents
- [`SCOPE.md`](SCOPE.md) — what is and is not in this repository
- [`spec/PqrstEstimationPractice.md`](spec/PqrstEstimationPractice.md) — the specification, v0.1
- [`PqrstPrompt.md`](PqrstPrompt.md) — the canonical end-of-session prompt

83
PqrstPrompt.md Normal file
View file

@ -0,0 +1,83 @@
# PQRST Prompt
The canonical end-of-session prompt. Paste the fenced block below — unmodified — after the substantive work of an agentic coding session is complete.
Specification: [`spec/PqrstEstimationPractice.md`](spec/PqrstEstimationPractice.md) (v0.1).
Do not add scoring dimensions inside PQRST. Do not run this prompt mid-session unless deliberately closing a phase.
---
```text
Please produce a retrospective PQRST-Estimate for this completed coding session.
Allocate exactly 100% of the session's effective engineering effort across these five dimensions and no others:
P — Main Problem: direct work producing the primary requested outcome — implementing the feature, fix, algorithm, integration, or other core deliverable.
Q — Quality and Tests: work establishing correctness, robustness, maintainability, and confidence — 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.
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 a planning target or productivity score.
2. The five values must be integers in 0..100 and must sum to exactly 100.
3. Estimate relative effective engineering attention — 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 or modules inspected or changed, tests written or run, documentation consulted, security or credential work handled, planning or coordination performed.
6. Do not force every category to be non-zero. S may legitimately be 0% and must not be inflated merely because security is generally important.
7. Prefer honest coarse estimates, normally in roughly 5-percentage-point increments, over false precision. If you cannot defend a split, round to tens and lower the confidence.
8. Report uncertainty only in the Confidence field. Never fold it into P, Q, R, S, or T.
9. "Dominant factors" must name concrete session facts, not restate the percentages.
10. If the session record is insufficient to estimate a category confidently, say so rather than inventing evidence.
Return exactly this format, and nothing before or after it:
PQRST-Estimate
P: <int>%
Q: <int>%
R: <int>%
S: <int>%
T: <int>%
Sum: 100%
Confidence: <low|medium|high>
Signature: P<int> Q<int> R<int> S<int> T<int>
Dominant factors: <one or two sentences naming the concrete drivers of the largest slices>
Notes: <optional; omit this line entirely if there is nothing to add>
```
---
## Optional add-on: per-dimension rationale
When the estimate is being read by a person rather than filed, append this to the prompt above:
```text
After the block, also give a one-line evidence-based rationale for each of the five dimensions, plus one sentence characterizing the overall session profile (implementation-heavy, quality-heavy, exploration-heavy, security-heavy, coordination-heavy, or mixed).
```
## Optional add-on: machine-collectable record
When results are being aggregated across many sessions, append:
```text
After the block, also emit the equivalent YAML record with keys p, q, r, s, t, total, profile, confidence, signature.
```
---
## Accepting or rejecting a result
Reject and re-run if any of the following is true:
- the five values are not integers summing to 100;
- `Confidence` is missing or not one of `low` / `medium` / `high`;
- `Signature` disagrees with the individual values;
- `Dominant factors` merely restates the numbers or says something like "mixed work across several areas";
- a sixth dimension has been introduced inside the 5-tuple;
- S is non-zero but no security-specific work actually occurred.

98
SCOPE.md Normal file
View file

@ -0,0 +1,98 @@
# Scope
This repository provides the means of **closing agentic coding sessions** using the PQRST estimation practice. It is a specification-and-prompt repository. It defines the practice, supplies the artifacts needed to perform it, and stops there.
See [`INTENT.md`](INTENT.md) for why.
---
## In scope
### 1. The specification
`spec/PqrstEstimationPractice.md` — the normative definition of PQRST: the five dimensions, the estimation rules, the collection point, the canonical result formats, validation constraints, derived views, the pattern catalog, and the practice rules. Versioned; currently **0.1**.
### 2. The closing prompt
`PqrstPrompt.md` — the canonical end-of-session prompt, kept in the repository root so it is trivially reachable at the moment a session ends. Includes the optional add-ons and the accept/reject checklist.
### 3. Record formats
The stored block record, the compact signature line, the optional human-readable table, and the optional YAML form — including the validation rules that make a record well-formed.
### 4. Interpretation guidance
Derived views (`P+Q`, `R+S+T`), example signatures, the pattern catalog, and correlation ideas — all as hypotheses for qualitative review, never as automatic conclusions.
### 5. Provenance
`history/` — the source drafts from which a specification version was consolidated, retained unmodified. New drafts are added; existing ones are not edited.
---
## Out of scope
### Tooling and automation
No collectors, parsers, validators, CLIs, linters, hooks, dashboards, or storage backends live here. The record format is specified precisely enough that such tools can be built — **elsewhere**. A reference validator may be reconsidered for a later version; it is not a commitment.
### Session storage
This repository defines what a record looks like. It does not hold anyone's records, prescribe a database, or specify a schema for a session corpus.
### Integration with any particular agent or harness
PQRST is deliberately agent-agnostic and model-agnostic. Wiring it into a specific harness, plugin, skill, or CI pipeline belongs to that harness's own repository.
### Scoring, benchmarking, and evaluation
No thresholds, no healthy-profile templates, no grading, no leaderboards, no comparison of agents or models on PQRST values. This is excluded on principle, not for lack of time — see [`INTENT.md`](INTENT.md).
### Prospective planning
No effort budgets, no target allocations, no pre-session PQRST plans.
### Extending the model
The acronym is closed at five letters. Proposals for a sixth dimension are out of scope. Proposals to expand an existing letter into subdimensions, or to add companion fields *outside* the 5-tuple (task type, outcome, cost, module id), are in scope for a future version.
### Empirical validation
This repository does not claim, and does not attempt to establish, that PQRST estimates are accurate, reproducible across estimators, or predictive of outcomes. The practice is offered as a structured judgment. Studying whether it holds up is legitimate work — it is not this repository's work.
---
## Boundaries and invariants
These hold across all versions:
1. **Exactly five dimensions**, named P, Q, R, S, T, with stable meanings.
2. **Retrospective only.** Nothing here is ever to be used as a planning target.
3. **Records are auditable.** A signature is never published without its evidence.
4. **Local files are the source of truth.** The specification governs; anything generated from it follows.
5. **`history/` is append-only.**
---
## Repository layout
```
INTENT.md why this practice exists and what it must not become
SCOPE.md this file
PqrstPrompt.md the canonical end-of-session prompt
README.md one-line orientation
spec/
PqrstEstimationPractice.md the specification (v0.1)
history/
20260905-*_chatgpt.md source draft, retained unmodified
20260905-*_grok.md source draft, retained unmodified
```
---
## Change process
- The specification is versioned. Substantive changes increment the version and record a line in its Appendix B version history.
- Changes that alter the meaning of a dimension, the validation rules, or the stored record format are **breaking**: they make older records less comparable, and must say so explicitly.
- Editorial changes — clarification, examples, wording — do not require a version bump.
- Source drafts in `history/` are never edited, only added to.

306
history/20260905-PqrstEstimationPractice_chatgpt.md Executable file
View file

@ -0,0 +1,306 @@
# 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.

291
history/20260905-PqrstEstimationPractice_grok.md Executable file
View file

@ -0,0 +1,291 @@
# PQRST Estimation Practice
A retrospective effort topology for agentic coding sessions.
PQRST-Estimate is a deliberately simple lens. It does not claim to measure tokens, wall-clock time, or compute. It records a comparative judgment of where a session’s *effective engineering attention* went, so that many sessions can be observed as a process rather than as isolated chats.
Use it at the end of a session. Collect it consistently. Interpret patterns over time.
---
## Definition
**PQRST-Estimate** is a retrospective estimate of the relative distribution of productive session effort across five engineering concerns.
It is an *assessment*, not telemetry.
| It is | It is not |
| --- | --- |
| A semantic allocation of attention | Elapsed time |
| A 100% comparative split | Token or tool-call accounting |
| Auditable with a short justification | An objective measurement |
| Useful in aggregate across sessions | A target to optimize in advance |
Percentages exist to make a qualitative judgment compact and comparable:
> “This session was research-heavy, moderately implementation-heavy, and contained little security work.”
---
## Dimensions
Keep exactly five dimensions. If more detail is needed later, expand a letter into subdimensions. Do not grow the acronym.
| Letter | Name | Counts as | Does not count as |
| --- | --- | --- | --- |
| **P** | Problem | Direct implementation and problem solving toward the requested outcome | Setup, exploration, verification, planning |
| **Q** | Quality | Tests, debugging, verification, robustness, correctness-oriented refactoring | Greenfield feature work that happens to compile |
| **R** | Research | Domain, repository, APIs, prior work, requirements, ambiguity resolution | Implementation that follows from already-clarified context |
| **S** | Security | Credentials, permissions, secrets, attack surface, policy and security constraints | Generic error handling with no security implication |
| **T** | Task organization | Planning, decomposition, tracking, coordination, tool and workflow management | The planned work itself once execution starts |
Overlaps are expected. Allocate by *primary purpose of the attention*, not by file type. A test written to discover the spec is mostly **Q** with a note that it also reduced **R**. Reconstructing architecture before writing code is **R**, not **P**.
**S** may legitimately be `0`. Do not inflate it to make the model look complete.
---
## Derived views
These are interpretive, not extra dimensions.
| View | Formula | Use |
| --- | --- | --- |
| Problem Focus | `P` | How much of the session was the nominal work |
| Direct Engineering | `P + Q` | Building and hardening the thing |
| Enabling Effort | `R + S + T` | Making the thing possible, allowed, and organized |
Do not call Enabling Effort “waste” or “overhead.” Research and security can be the most valuable work in the session. The question is whether the *mix* fits the class of task.
Healthy is contextual:
- `P90 Q2 R3 S0 T5` can be worse than `P55 Q30 R10 S0 T5`
- Do not maximize **P**. Learn what good signatures look like per task type.
---
## When to collect
Run the estimate once, at the natural end of a session or a clearly bounded work unit (one ticket, one vertical slice, one “stop here” checkpoint).
Do not collect mid-stream unless you are closing a phase on purpose. Mid-session estimates mix unfinished work with planning residue and are hard to compare.
If the session spanned several distinct modes (explore, then implement, then harden), you may emit **one overall estimate** plus optional phase notes. The stored record is still a single 5-tuple unless you explicitly version phases.
---
## Canonical prompt
Paste this at the end of the session. Do not add extra scoring dimensions inside PQRST.
```text
Please give me a PQRST-Estimate for this session.
Allocate exactly 100% of the session's effective engineering effort across:
- P = solving the main problem (direct implementation and problem solving)
- Q = quality, testing, verification, debugging, robustness
- R = research, understanding, repository/API/domain context, requirements clarification
- S = security, permissions, credentials, secrets, attack surface, policy constraints
- T = task organization, planning, decomposition, tracking, coordination, workflow management
Rules:
- This is a retrospective estimate of relative attention, not telemetry of time, tokens, or tool calls.
- Allocate by primary purpose of the work, even when activities overlapped.
- S may be 0 when security was not in scope.
- Percentages must be integers and must sum to 100.
Return exactly this format and nothing else before or after it:
PQRST-Estimate
P: <int>%
Q: <int>%
R: <int>%
S: <int>%
T: <int>%
Sum: 100%
Confidence: <low|medium|high>
Signature: P<int> Q<int> R<int> S<int> T<int>
Dominant factors: <one or two sentences naming the concrete drivers of the largest slices>
Notes: <optional; omit the line if none>
```
Confidence sits *outside* the five-dimensional model. Uncertainty must not be folded into P, Q, R, S, or T.
---
## Canonical result format
### Stored record
Use the block form as the source of truth. The `Signature` line is the compact key for logs, tables, and trend charts.
```text
PQRST-Estimate
P: 25%
Q: 15%
R: 45%
S: 0%
T: 15%
Sum: 100%
Confidence: medium
Signature: P25 Q15 R45 S0 T15
Dominant factors: Repository architecture and implicit module boundaries had to be reconstructed before any implementation; planning the exploration path was a material share of the work.
Notes: Security was out of scope.
```
### Compact line
For transcripts, dashboards, and commit messages:
```text
P25 Q15 R45 S0 T15 | confidence: medium | Repository architecture had to be reconstructed before implementation.
```
Parse rule: five integer fields in P/Q/R/S/T order, optional confidence, then free-text justification.
### Validation
A result is valid only if all of the following hold:
1. Each of P, Q, R, S, T is an integer from 0 to 100 inclusive.
2. `P + Q + R + S + T = 100`.
3. Confidence is one of `low`, `medium`, `high`.
4. `Dominant factors` names *concrete session facts*, not restatements of the percentages.
5. No sixth engineering dimension is introduced in the 5-tuple.
If the model cannot justify a split, prefer coarser rounded tens (`P30 Q20 R30 S0 T20`) and `confidence: low` over fake precision.
---
## Example signatures
These are illustrations, not targets.
```text
P70 Q20 R5 S0 T5
```
Well-understood implementation in a familiar area. Little discovery, some verification.
```text
P25 Q15 R45 S0 T15
```
Exploratory work in an unfamiliar system. Context reconstruction dominated.
```text
P20 Q20 R10 S35 T15
```
Access control, credentials, or security policy dominated the work.
```text
P20 Q15 R20 S0 T45
```
More energy managing the work than doing the work. Inspect agent workflow, task grain, and tool orchestration.
```text
P55 Q30 R10 S0 T5
```
Creation plus real verification. Often healthier than a very high-P session with almost no Q.
```text
P40 Q35 R5 S15 T5
```
Hardening a known surface that includes a security constraint.
---
## Pattern catalog
Interpret *persistence* and *task class*, not a single session.
| Pattern | Possible interpretation |
| --- | --- |
| Persistently high R | Architecture, specification, or repository context is insufficiently explicit |
| Persistently high T | Task grain, agent workflow, or coordination is inefficient |
| Very high P, very low Q | Fast implementation with accumulating verification debt |
| Rising Q late in a project | Stabilization / hardening phase |
| Repeated S spikes | Credential, IAM, or security-ergonomics problem in the environment |
| Falling R over successive sessions on the same repo | Repository knowledge and documentation are improving |
| Falling P, rising Q | Transition from creation to stabilization |
| High Enabling Effort (`R+S+T`) on a supposedly routine change | The environment around P is the real problem |
| High Direct Engineering (`P+Q`) with high confidence | Session matched a well-scoped implementation or hardening task |
A single high-R session on a new codebase is normal. High R on the fifth session in the same module is a process signal.
---
## Correlation ideas
PQRST becomes process telemetry when stored next to outcomes, not when stared at in isolation.
Useful companions:
- task success / partial success / revert
- test energy (tests added, tests run, failures, flakiness)
- human interventions and redirects
- elapsed cost (time or tokens) as a separate column — never substitute it for PQRST
- task type label: `feature`, `bugfix`, `explore`, `migrate`, `harden`, `incident`
- repository or module id
Questions the joined data can answer:
- Do high-T sessions fail more often, or just cost more?
- Does falling R predict fewer human redirects?
- Do high-P / low-Q sessions generate follow-up bugfix sessions?
- Which task types have a stable signature worth using as a baseline?
---
## Practice rules
1. **Estimate after the work, do not steer toward a signature.** PQRST is a lens, not a KPI.
2. **Keep five dimensions.** Expand a letter later if needed; do not add U–Z to the core model.
3. **Write the justification first in your head, then the numbers.** If you cannot name the dominant factors, the split is not ready.
4. **Round to the resolution you can defend.** Integers are required; 1% differences are usually noise.
5. **Leave S at 0 when it was 0.** A forced 5% security slice poisons trend data.
6. **Treat Enabling Effort as context, not guilt.** The diagnostic is misfit to the task, not “too little P.”
7. **Compare like with like.** An explore session and a one-line fix should not share a “healthy” template.
8. **Store the signature line plus the dominant-factors sentence.** Numbers without the sentence are not auditable.
---
## What a good estimate sounds like
Weak:
```text
P: 57%
Q: 14%
R: 19%
S: 2%
T: 8%
Dominant factors: Mixed work across several areas.
```
Strong:
```text
P: 25%
Q: 15%
R: 45%
S: 0%
T: 15%
Sum: 100%
Confidence: medium
Signature: P25 Q15 R45 S0 T15
Dominant factors: Existing auth middleware was undocumented and contradicted the README, so most attention went to reconstructing the request path before changing behavior.
```
The second record can be compared to the next session in the same module. The first cannot.
---
## Minimal operator checklist
At session end:
1. Run the canonical prompt.
2. Confirm the five percentages sum to 100.
3. Keep or reject the result based on whether `Dominant factors` cites concrete session facts.
4. Store `Signature`, `Confidence`, `Dominant factors`, task type, and outcome.
5. Do not discuss the estimate during the next session unless you are changing process on purpose.

410
spec/PqrstEstimationPractice.md Normal file
View file

@ -0,0 +1,410 @@
# PQRST Estimation Practice
**Version:** 0.1
**Status:** Draft
**Date:** 2026-09-05
**Supersedes:** `history/20260905-PqrstEstimationPractice_chatgpt.md`, `history/20260905-PqrstEstimationPractice_grok.md`
---
## 1. Purpose
PQRST is a lightweight retrospective audit for agentic coding sessions.
It answers one question:
> **Where did the effective engineering effort of this session actually go?**
PQRST is **not** a planning tool, a target allocation, a productivity score, or a precise accounting method. It is a structured post-session estimate that makes the character of a session visible and comparable over time.
The value 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.
### Design principle
> **PQRST should make the session more legible without making the session perform for the metric.**
### What it is and is not
| It is | It is not |
| --- | --- |
| A semantic allocation of engineering attention | Elapsed wall-clock time |
| A comparative 100% split | Token, compute, or tool-call accounting |
| Auditable via a short evidence statement | An objective measurement |
| Useful in aggregate across sessions | A target to optimize in advance |
---
## 2. The Five Dimensions
Keep exactly five dimensions. If more detail is needed later, expand a letter into subdimensions. **Do not grow the acronym.**
| Letter | Name | Counts as | Does not count as |
| --- | --- | --- | --- |
| **P** | Main Problem | Direct implementation and problem solving toward the requested outcome | Setup, exploration, verification, planning |
| **Q** | Quality and Tests | Tests, debugging for correctness, verification, robustness, correctness-oriented refactoring | Greenfield feature work that merely happens to compile |
| **R** | Research and Context | Domain, repository, API, prior-work, and requirement understanding; ambiguity resolution | Implementation that follows from already-clarified context |
| **S** | Security and Credentials | Credentials, permissions, secrets, attack surface, trust boundaries, policy constraints | Generic error handling with no security implication |
| **T** | Task Organization | Planning, decomposition, tracking, coordination, tool and workflow management | The planned work itself, once execution starts |
### P — Main Problem
Effort spent directly producing the primary requested outcome:
- implementing the feature or fix;
- changing application logic;
- writing the algorithm;
- creating the requested integration;
- resolving the main defect;
- producing the principal deliverable.
P represents **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:
- unit, integration, end-to-end, regression, or property tests;
- test fixtures and verification infrastructure;
- edge-case handling, validation, error handling;
- debugging performed primarily to establish correctness;
- refactoring for maintainability after the main behavior works;
- static analysis, linting, type checking;
- 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:
- 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:
- 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%**. Do not inflate S merely because secure engineering is generally desirable, or to make a record look complete. A forced 5% security slice poisons trend data.
### T — Task Organization
Effort spent structuring, sequencing, tracking, and coordinating the work rather than directly solving or validating the technical problem:
- 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.
---
## 3. Estimation Rules
**R1 — Estimate retrospectively.** Generate PQRST only after the substantive session work is complete. Never use a desired PQRST profile as a planning target.
**R2 — Allocate exactly 100%.** The five values are integers in `0..100` and MUST sum to exactly 100.
**R3 — Estimate effective engineering effort, not telemetry.** The estimate represents the relative share of meaningful engineering attention. It is not a reconstruction of wall-clock time, token usage, tool-call counts, compute consumption, human review time, or any hidden internal model process.
**R4 — Ground every non-zero category in observable session activity.** Cite concrete evidence: files or modules inspected or changed, tests written or executed, documentation consulted, credentials or trust boundaries handled, plans or decomposition performed. Avoid generic rationales such as "some testing was done" when concrete evidence exists.
**R5 — Attribute overlapping work by primary purpose.** Categories overlap by design. Assign effort by the *primary reason the activity was undertaken at that moment*, and do not double-count.
| Activity | Category |
| --- | --- |
| 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** (note that it also served Q) |
| Changing authorization logic the feature requires | split **P** / **S** by how much was implementation versus security-specific reasoning |
| Repeatedly reorganizing work after losing track of scope | **T** |
**R6 — Do not optimize for a "good" profile.** There is no universally correct distribution. An exploratory session may be R-heavy; a stabilization session Q-heavy; a credential integration S-heavy; a routine change P-heavy. Describe the session faithfully.
**R7 — Prefer coarse honesty over theatrical precision.** Estimate in roughly 5-percentage-point increments unless the distribution is unusually clear. `35%` is more credible and more useful than `33.7%`. If a split cannot be defended, round to tens and lower the confidence.
**R8 — Include zero values explicitly.** Always report all five dimensions. A zero is information.
**R9 — Keep confidence outside the model.** Uncertainty is reported as a separate `Confidence` field and must never be folded into P, Q, R, S, or T.
**R10 — Do not introduce a sixth dimension.** Additional engineering concerns are expressed as subdimensions of an existing letter or as separate companion fields, never inside the 5-tuple.
---
## 4. When to Collect
Run the estimate **once**, at the natural end of a session or a clearly bounded work unit — one ticket, one vertical slice, one deliberate "stop here" checkpoint.
Do not collect mid-stream unless closing a phase on purpose. Mid-session estimates mix unfinished work with planning residue and are hard to compare.
If a session spanned several distinct modes (explore, then implement, then harden), emit **one overall estimate** plus optional phase notes. The stored record remains a single 5-tuple unless phases are explicitly versioned.
---
## 5. Canonical Result Format
### 5.1 Stored record (source of truth)
The block form is the authoritative record. The `Signature` line is the compact key for logs, tables, and trend charts.
```text
PQRST-Estimate
P: 25%
Q: 15%
R: 45%
S: 0%
T: 15%
Sum: 100%
Confidence: medium
Signature: P25 Q15 R45 S0 T15
Dominant factors: Existing auth middleware was undocumented and contradicted the README, so most attention went to reconstructing the request path before changing behavior.
Notes: Security was out of scope.
```
`Notes:` is optional; omit the line entirely if there is nothing to add.
### 5.2 Compact line
For transcripts, dashboards, and commit messages:
```text
P25 Q15 R45 S0 T15 | confidence: medium | Repository architecture had to be reconstructed before implementation.
```
Parse rule: five integer fields in P/Q/R/S/T order, optional confidence, then free-text justification.
### 5.3 Expanded human-readable form (optional)
When the estimate is presented to a person rather than stored, the block form MAY be accompanied by a per-dimension table. It is a presentation of the same record, never a substitute for it.
```markdown
## PQRST Estimate
| Dimension | Estimate | Evidence / rationale |
|---|---:|---|
| P — Main Problem | NN% | One concise statement grounded in implementation work actually performed. |
| Q — Quality and Tests | NN% | One concise statement grounded in tests, verification, debugging, or quality work actually performed. |
| R — Research and Context | NN% | One concise statement grounded in repository exploration, documentation, tracing, or requirement clarification actually performed. |
| S — Security and Credentials | NN% | One concise statement grounded in security, permissions, credentials, secrets, or isolation work actually performed; 0% when none occurred. |
| T — Task Organization | NN% | One concise statement grounded in planning, decomposition, sequencing, or coordination actually performed. |
| **Total** | **100%** | |
**Session profile:** One sentence characterizing the session — implementation-heavy, exploration-heavy, hardening-heavy, security-heavy, coordination-heavy, or mixed — including the principal reason.
**Estimate confidence:** High / Medium / Low — one short reason based on how observable and distinguishable the session activities were.
```
### 5.4 Machine-friendly form (optional)
When results are collected across many sessions:
```yaml
pqrst:
p: 25
q: 15
r: 45
s: 0
t: 15
total: 100
profile: exploration-heavy # implementation-heavy | quality-heavy | exploration-heavy | security-heavy | coordination-heavy | mixed
confidence: medium # high | medium | low
signature: P25 Q15 R45 S0 T15
```
Values are percentages and SHOULD be stored as integers.
### 5.5 Validation
A result is valid only if **all** of the following hold:
1. Each of P, Q, R, S, T is an integer in `0..100`.
2. `P + Q + R + S + T = 100`.
3. `Confidence` is one of `low`, `medium`, `high`.
4. `Dominant factors` names **concrete session facts**, not a restatement of the percentages.
5. No sixth engineering dimension appears inside the 5-tuple.
6. `Signature` agrees with the five individual values.
If a category cannot be estimated from the session record, say so explicitly rather than inventing evidence.
---
## 6. Derived Views
These are interpretive lenses, not extra dimensions.
| View | Formula | Use |
| --- | --- | --- |
| Problem Focus | `P` | How much of the session was the nominal work |
| Direct Engineering | `P + Q` | Building and hardening the thing |
| Enabling Effort | `R + S + T` | Making the thing possible, allowed, and organized |
Do **not** call Enabling Effort "waste" or "overhead." Research and security are often the most valuable work in a session. The diagnostic question is whether the *mix fits the class of task*, not whether P is large.
Healthy is contextual: `P90 Q2 R3 S0 T5` can be a worse session than `P55 Q30 R10 S0 T5`.
---
## 7. Example Signatures
Illustrations, not targets.
| Signature | Reading |
| --- | --- |
| `P70 Q20 R5 S0 T5` | Well-understood implementation in a familiar area. Little discovery, some verification. |
| `P55 Q30 R10 S0 T5` | Creation plus real verification. Often healthier than a very high-P session with almost no Q. |
| `P25 Q15 R45 S0 T15` | Exploratory work in an unfamiliar system. Context reconstruction dominated. |
| `P20 Q20 R10 S35 T15` | Access control, credentials, or security policy dominated the work. |
| `P40 Q35 R5 S15 T5` | Hardening a known surface that includes a security constraint. |
| `P20 Q15 R20 S0 T45` | More energy managing the work than doing the work. Inspect agent workflow, task grain, and tool orchestration. |
---
## 8. Pattern Catalog
Interpret **persistence and task class**, never a single session. These are hypotheses for review, not automatic conclusions.
| Pattern | Possible interpretation |
| --- | --- |
| High P, very low Q | Fast implementation with accumulating verification debt |
| High Q | Stabilization, hardening, debugging, or test-oriented work |
| Rising Q as a project matures | Transition from creation toward stabilization and production readiness |
| High R on first sessions in a repo | Normal exploration of an unfamiliar system |
| Persistently high R on repeated sessions | Architecture, specification, or repository context is insufficiently explicit |
| Falling R over successive sessions | Growing repository familiarity or improving contextual support |
| High S | Security-sensitive task, credential friction, permission complexity, or trust-boundary work |
| Repeated S spikes | Credential, IAM, or security-ergonomics problem in the environment |
| Unexpectedly zero S on security-relevant work | Possible missing security attention; warrants qualitative review, not automatic judgment |
| High T | Significant coordination burden; healthy for complex work, or a sign of workflow thrashing |
| Falling T over repeated similar sessions | Better task framing, stronger context, or improved agent workflow |
| High Enabling Effort on a supposedly routine change | The environment around P is the real problem |
| High Direct Engineering with high confidence | Session matched a well-scoped implementation or hardening task |
A single high-R session on a new codebase is normal. High R on the fifth session in the same module is a process signal.
---
## 9. Correlation
PQRST becomes process telemetry when stored next to outcomes, not when stared at in isolation. Useful companion fields:
- task success / partial success / revert;
- test energy (tests added, tests run, failures, flakiness);
- human interventions and redirects;
- elapsed cost (time or tokens) as a **separate** column — never a substitute for PQRST;
- task type label: `feature`, `bugfix`, `explore`, `migrate`, `harden`, `incident`;
- repository or module id;
- agent / model / workflow used.
Questions the joined data can answer:
- Do high-T sessions fail more often, or just cost more?
- Does falling R predict fewer human redirects?
- Do high-P / low-Q sessions generate follow-up bugfix sessions?
- Which task types have a stable signature worth using as a baseline?
---
## 10. Practice Rules
1. **Estimate after the work; do not steer toward a signature.** PQRST is a lens, not a KPI.
2. **Keep five dimensions.** Expand a letter later if needed; do not add U–Z to the core model.
3. **Form the justification first, then the numbers.** If the dominant factors cannot be named, the split is not ready.
4. **Round to the resolution you can defend.** Integers are required; 1% differences are noise.
5. **Leave S at 0 when it was 0.**
6. **Treat Enabling Effort as context, not guilt.** The diagnostic is misfit to the task, not "too little P."
7. **Compare like with like.** An explore session and a one-line fix do not share a healthy template.
8. **Store the signature line plus the dominant-factors sentence.** Numbers without the sentence are not auditable.
9. **Preserve the rationales, not only the percentages.**
10. **Do not rank developers, agents, or teams on raw percentages** without additional outcome evidence.
11. **Do not discuss a stored estimate during the next session** unless changing process on purpose.
---
## 11. What a Good Estimate Sounds Like
Weak — percentages restated as prose, false precision, a token S slice:
```text
P: 57%
Q: 14%
R: 19%
S: 2%
T: 8%
Dominant factors: Mixed work across several areas.
```
Strong — coarse, auditable, grounded in concrete session facts:
```text
P: 25%
Q: 15%
R: 45%
S: 0%
T: 15%
Sum: 100%
Confidence: medium
Signature: P25 Q15 R45 S0 T15
Dominant factors: Existing auth middleware was undocumented and contradicted the README, so most attention went to reconstructing the request path before changing behavior.
```
The second record can be compared to the next session in the same module. The first cannot.
---
## 12. Operator Checklist
At session end:
1. Run the canonical prompt (`PqrstPrompt.md` in the repository root).
2. Confirm the five percentages are integers summing to 100.
3. Keep or reject the result based on whether `Dominant factors` cites concrete session facts.
4. Store `Signature`, `Confidence`, `Dominant factors`, task type, and outcome.
5. Review distributions across sessions rather than optimizing any single session.
6. Investigate surprising changes or persistent patterns qualitatively.
---
## Appendix A — Terminology
| Term | Meaning |
| --- | --- |
| **PQRST-Estimate** | A single retrospective 5-tuple for one bounded session, plus confidence and dominant factors |
| **Signature** | The compact `P<int> Q<int> R<int> S<int> T<int>` key |
| **Profile** | A one-word characterization of the session shape |
| **Derived view** | An interpretive combination of dimensions; never a sixth dimension |
| **Enabling Effort** | `R + S + T` |
| **Direct Engineering** | `P + Q` |
## Appendix B — Version History
| Version | Date | Change |
| --- | --- | --- |
| 0.1 | 2026-09-05 | Initial consolidation of the two independent 2026-09-05 drafts into one specification. The block/signature record was adopted as the source of truth; the per-dimension table was retained as an optional presentation form. |