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

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
2026-09-05 20:27:36 +02:00 · 2026-09-05 20:27:36 +02:00 · 4986a87773
commit 4986a87773
parent c6723a6aca
6 changed files with 1237 additions and 0 deletions
--- a/history/20260905-PqrstEstimationPractice_chatgpt.md
+++ b/history/20260905-PqrstEstimationPractice_chatgpt.md
@ -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.
--- a/history/20260905-PqrstEstimationPractice_grok.md
+++ b/history/20260905-PqrstEstimationPractice_grok.md
@ -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.