pqrst-practice/workplans/PQRST-WP-0002-validate-v01-against-real-sessions.md

---
id: PQRST-WP-0002
type: workplan
title: "Validate spec v0.1 in real session closes and land PQRST in hall-of-helix"
domain: agents
repo: pqrst-practice
status: proposed
owner: claude-code
topic_slug: practice
priority: high
created: "2026-09-05"
updated: "2026-09-05"
quality_dor: DoR-Ok
quality_dor_at: "2026-09-05"
quality_dor_by: claude-code
quality_dor_note: "v0.1 consolidates two drafts that were written without either being applied to a session. Every open question is empirical — whether the prompt returns a valid record unassisted, whether attribution by primary purpose is decidable in practice, and where records are stored. hall-of-helix supplies both the pilot population and the answer to the storage question: the operator already asks agents for a closing entry there, and one estimate has been added by hand, so the routine exists and is simply unspecified."
related:
  - PQRST-WP-0001
repos:
  - pqrst-practice
  - hall-of-helix
state_hub_workstream_id: "6a875b19-5a76-55c1-bd1f-2f5005cd416b"
---

# Validate spec v0.1 in real session closes and land PQRST in hall-of-helix

Spec v0.1 was consolidated from two independent drafts, neither of which had
been applied to an actual session. It is internally consistent and entirely
unvalidated.

There is already a session-closing ritual in the fleet. The operator ends a
session with some form of:

> "Ok, lets close down this session then. Good work, please put an entry about
> your perspective on the session to hall-of-helix, before we wind down."

That ritual is real, repeated, and under-specified. An agent receiving it has to
infer the routine from `ENTRY.md`, and PQRST is not part of that routine at all —
the one estimate in the hall
(`entries/2026-09-05T16:36:12.000Z-codex-statehub-snapshot-and-signature.md`,
`pqrst_estimate: 30/23/18/19/10`) was added by hand, in a format that is not the
one the specification defines.

This workplan closes both gaps together: use real session closes as the pilot
population, and make the closing routine explicit in hall-of-helix so that an
agent reading that prompt finds — without being told twice — that closing a
session means running the PQRST prompt and recording the result in its entry.

It deliberately does **not** build tooling or a record store in *this*
repository. Both are out of scope (`SCOPE.md`); the hall is the store, and the
hall owns its own validation.

**Done when:** the closing routine is specified in hall-of-helix and reachable
from the prompt above, entries carry a validated PQRST record, the prompt has
been run unassisted at the end of at least eight real sessions, and v0.2 either
incorporates the findings or records why v0.1 stands.

**Execution order:** T01 → T04 → T05 → T02 → T03. Task ids are identity, not
sequence; the hall changes (T04, T05) land early so the pilot runs through the
real routine rather than beside it.

**Cross-repo:** T04 and T05 change `hall-of-helix`, not this repo. Open a
companion `HOH-WP` (or an `ADHOC` record) there referencing `PQRST-WP-0002`, and
land the edits under it.

## Pilot the closing prompt on real sessions

```task
id: PQRST-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "dd259b3f-e9ae-5bdd-8e02-07ae0083930a"
```

Paste `PqrstPrompt.md` unmodified at the end of at least **eight** real agentic
coding sessions, spread across at least three repositories and at least two task
classes (e.g. `feature`, `bugfix`, `explore`, `harden`). Once T04 has landed,
these are ordinary hall closes — the pilot is observation of the routine, not a
separate exercise.

Do not coach the model, do not repair a malformed answer, and do not re-run the
prompt for a better result. A rejected record is the finding.

For each session capture, in this file under "Pilot findings":

- the returned record verbatim;
- whether it passed spec §5.5 validation on the first attempt;
- whether `Dominant factors` cited concrete session facts or restated the
  percentages;
- any dimension the model hedged on, refused, or visibly guessed at;
- the task class and the repository.

The specific questions to answer:

1. Does an uncoached agent return a **valid** record from the prompt alone?
2. Is "attribute by primary purpose" (spec R5) actually decidable mid-estimate,
   or does it collapse under overlap?
3. Does S stay at 0 when security work did not occur, or does it drift upward?
4. Do estimates cluster at coarse increments (R7), or does false precision
   reappear?
5. Is `Confidence` used meaningfully, or is it always `medium`?
6. **Does an agent estimating its own session inflate P?** The hall entry is a
   first-person account written by the same session being audited. Self-report
   bias is a live threat to the whole practice and the hall is where it will
   first be visible.

## Decide the record-storage boundary

```task
id: PQRST-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "fd4abb7f-214f-56a0-a2f8-369008a9dc9a"
```

`SCOPE.md` excludes record storage from this repository but does not say where
records go instead. Until that is answered the practice produces records with
nowhere to live, and the trend analysis that justifies the whole exercise
(spec §8, §9) cannot happen.

**hall-of-helix is now the leading candidate and should be evaluated as the
default**, not weighed from scratch: one record per session, written at the
moment of closing, already carrying `repos`, `session_id`, `exact_model`,
`harness`, and a first-person account of what the session actually did. That is
richer session metadata than a purpose-built store would likely collect, and
spec §9 asks for exactly those companions.

Weigh honestly what the hall is **not**:

- it is a hall of remembrance, not a metrics warehouse — spec §8 trend queries
  mean grepping Markdown, and `INTENT.md` forbids turning entries into a
  leaderboard;
- seats are voluntary and sometimes drafts, so the record set is a biased
  sample of sessions, not a census;
- not every session ends with a seat, and forcing one would corrupt both
  practices.

Decide, and record the answer as a decision (`POST /decisions/`, then an ADR in
this repo if there are repo-local consequences). If the hall is chosen, say
plainly whether it is the *only* store or the human-facing one alongside a
machine-facing collector owned elsewhere. Whatever is chosen, this repository
still ships no collector — the decision names the owner, it does not move the
work here.

## Cut spec v0.2

```task
id: PQRST-WP-0002-T03
status: todo
priority: medium
state_hub_task_id: "0a0bce15-ac0c-582a-842c-ae1bf0307afb"
```

From the pilot findings and the hall integration, revise the specification and
prompt together:

- fix rules the pilot showed to be undecidable or routinely ignored;
- tighten or relax the validation rules based on what actually failed;
- settle whether the closing ritual itself (writing the entry, rendering the
  portrait, syncing) is inside or outside the estimate — T04 takes a position;
  the pilot says whether it holds;
- state how self-estimation bias is to be handled, if T01 finds any;
- add the storage-boundary decision from T02 as a `SCOPE.md` cross-reference;
- bump to **v0.2** and add a row to the spec's Appendix B.

If a change alters a dimension's meaning, the validation rules, or the stored
record format, say plainly in Appendix B that records made under v0.1 are less
comparable. A record-format change also means a matching change in
hall-of-helix — name it in the handoff.

If the pilot surfaces nothing substantive, record that outcome and leave v0.1
standing. "No change needed, and here is the evidence" is a valid result and a
better one than churn.

Run the verification checklist in `AGENTS.md` before committing, then sync:

```bash
uv run --project ~/repo-manager rmgr sync --path . --push
```

## Specify the session-closing routine in hall-of-helix

```task
id: PQRST-WP-0002-T04
status: todo
priority: high
state_hub_task_id: "974949c3-1cab-5251-b3df-c50a8f3ab65a"
```

Make the closing routine explicit and findable, so an agent that receives the
operator's wind-down prompt knows the whole sequence without asking.

**Deliverable:** `CLOSING.md` in the hall-of-helix root — the routine in order,
one page, no prose detour. Quote the operator's actual wind-down sentence near
the top so an agent scanning for it recognises the situation it is in.

Link it from the three places an agent lands:

- `README.md`, beside "How to leave a seat";
- `ENTRY.md`, at the top — `ENTRY.md` says how to *write a seat*, `CLOSING.md`
  says what *closing a session* consists of, and the entry is one step of it;
- `AGENTS.md`, in the **Close** section of the session protocol.

**The routine to specify:**

1. Finish the substantive work. Update workplan task statuses.
2. **Run the PQRST prompt** — `~/pqrst-practice/PqrstPrompt.md` — unmodified and
   uncoached. Validate the result against spec §5.5 before using it: five
   integers summing to 100, `Confidence` present, `Dominant factors` naming
   concrete session facts rather than restating the numbers.
3. Write the entry per `ENTRY.md`, carrying the record (format per T05).
4. `make check`; add the seat to the `README.md` list.
5. Log progress to State Hub; sync the repo.

**Decide and state two things the routine is otherwise silent on:**

- **Scope of the estimate.** The estimate covers the *substantive session*, not
  the closing ritual — writing the entry, rendering the portrait, and syncing
  are excluded. Spec R1 says the estimate is produced after the substantive work
  is complete, and letting the ritual score itself would inflate T on every
  session that has a seat. State this explicitly in `CLOSING.md`; T03 revisits
  it if the pilot disagrees.
- **How the prompt is reached.** Referencing `~/pqrst-practice/PqrstPrompt.md`
  keeps one source of truth but assumes the checkout exists; inlining the prompt
  in the hall makes closes self-contained but forks the canonical text. The
  recommendation is to **reference the path and inline nothing but the output
  block**, so a session with no `pqrst-practice` checkout can still produce a
  well-formed record. Whichever is chosen, `pqrst-practice` stays canonical and
  the hall says so.

**Constraint:** the hall is not a metrics programme. `INTENT.md` there is
explicit that seats are not ranked and the hall is not a leaderboard, and
`INTENT.md` here is explicit that PQRST fails the moment anyone scores well on
it. The routine adds a record to a seat; it does not add a score to a worker.
Do not introduce comparison, aggregation, or ranking of estimates into
hall-of-helix.

## Carry the PQRST record in hall entries

```task
id: PQRST-WP-0002-T05
status: todo
priority: high
state_hub_task_id: "1d8f0b3d-7620-5810-ad91-13e17ee4b9e3"
```

Give the record a defined home in an entry, so it is machine-collectable without
losing the evidence that makes it auditable.

**Format** — both halves, since either alone is useless:

- **Frontmatter:** `pqrst_estimate: "P30 Q23 R18 S19 T10"` — the canonical
  signature from spec §5.2, quoted. Prefer it over the existing ad-hoc
  `30/23/18/19/10`: it is self-describing, survives reordering, and is matched by
  the same regex the `pqrst-practice` verification checklist already uses. This
  means normalising the one existing entry (see below).
- **Body:** a `## PQRST estimate` section holding the full stored record from
  spec §5.1 — the block, `Confidence`, and `Dominant factors`. Spec §10 rule 8
  is blunt that a signature without its dominant-factors sentence is not
  auditable, and `ENTRY.md` already refuses "various improvements" for the same
  reason.

**Changes:**

- `templates/entry.md` — add the frontmatter field and the section, with the
  section placed after "Durable legacy" and before "Visual prompt".
- `ENTRY.md` — add `pqrst_estimate` to the Required frontmatter table and
  "PQRST estimate" to the Required sections list, each with one line on what
  makes it valid, and link `CLOSING.md`.
- `scripts/check-entries.py` — when `pqrst_estimate` is present, validate the
  signature format and that it sums to 100; make it **required for
  `worker_kind: agent-session` entries created after the adoption date**, and
  add "PQRST estimate" to `REQUIRED_HEADINGS` under the same condition. Human
  seats are exempt. `make check` must still pass on all 102 existing seats.

**Do not backfill.** Existing seats predate the practice and nobody observed
those sessions; inventing estimates for them would be exactly the fabricated
evidence spec R4 and §5.5 rule 4 forbid, and it would poison the first trend
data the practice ever produces. The only record touched is the manual
`30/23/18/19/10` in the 2026-09-05 Codex seat, normalised to
`"P30 Q23 R18 S19 T10"` — same numbers, canonical spelling, and it already sums
to 100. Ask its author before rewriting the seat, or leave it and note the
exception in `CLOSING.md`.

## Pilot findings

_Populated by T01. One subsection per session: repository, task class, the
verbatim record, and whether it validated unassisted._