pqrst-practice/SCOPE.md

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

For sessions that voluntarily leave a hall entry, **hall-of-helix is the default
human-facing store** and owns entry storage and consumer validation. It is not
the only permitted store, and no separate machine-facing collector is selected
or commissioned. Seats are a biased sample, not a session census; no seat is
required just to retain an estimate. See
[ADR-002 — Record storage boundary](docs/adr/0002-record-storage-boundary.md).

### 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                        orientation and entry points
AGENTS.md                        agent instructions, developer workflow, verification checklist
spec/
  PqrstEstimationPractice.md     the specification (v0.1)
history/
  20260905-*_chatgpt.md          source draft, retained unmodified
  20260905-*_grok.md             source draft, retained unmodified
workplans/                       work records for this repo (State Hub convention)
```

State Hub integration files — `.custodian-brief.md`, `.repo-classification.yaml`,
and `WORK-RECORDS.md` — are generated and kept in sync by `statehub` /
`repo-manager`. They are not edited by hand.

The repo is registered in the Custodian State Hub under domain `agents`, topic
`practice` ("prestructured actions that are less complex than a process but more
ambitious and structured than a task"), with workplan prefix `PQRST-WP`.

---

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