pqrst-practice/spec/PqrstEstimationPractice.md

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.

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:

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.

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

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:

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:

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.