Skip to content

Commit ef2fc87

Browse files
tedsluisclaude
tedsluis
and
claude
committed
docs: add ai-sessions/ AI-prompt/result logging convention
Chat transcripts disappear on /clear or session end, losing the record of what an AI agent was actually asked and what it produced. Adds a binding convention (PROJECT_RULES.md rule 13a, AI_SESSION_LOG_PROCEDURE.md) to log every substantive AI-agent prompt/result pair permanently into ai-sessions/, with its own numbering registry (ai-sessions/INDEX.md) kept separate from id_registry.csv's existing CAP/ADR/Test-ID scope. Bootstraps entry 0001 from the just-completed deep V1-without-GMS cross-check (moved from the untracked DEEP_CROSSCHECK_PROGRESS_2026-09-07.md at repo root), and adds entry 0002: a maintenance prompt, ready to run in a new session, that (a) hardens the logging procedure with a mandatory reading-order rule and a rule for updating a RESULT's status from a later session, (b) implements 0001's Phase 4 proposals under explicit maintainer sign-off, and (c) scopes remaining work toward PROTOCOL.md V1-readiness. Also extends scripts/lint_docs.py's placeholder/historical-reference exemptions so the new convention's own template filenames and the DEEP_CROSSCHECK_PROGRESS_2026-09-07.md rename don't false-positive as dead references. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RxFpZZLKKeVeHvEWjxEA68
1 parent 075187e commit ef2fc87

8 files changed

Lines changed: 1167 additions & 0 deletions

‎AI_SESSION_LOG_PROCEDURE.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# AI_SESSION_LOG_PROCEDURE.md — AI Session Prompt/Result Logging
2+
3+
**Purpose:** every substantive prompt given to an AI agent working on this project (Claude Code, or
4+
another tool per `WORKSTATION_PREPARATIONS.md`'s cross-validation workflow), and that agent's
5+
resulting output/report, is saved permanently into `ai-sessions/` under the fixed naming scheme
6+
below — instead of living only in a chat transcript that disappears when the session ends or is
7+
cleared. This document is the *how*; `ai-sessions/INDEX.md` is the *lookup table* this procedure's
8+
numbering discipline depends on. See `PROJECT_RULES.md` §5 for the binding rule this procedure
9+
implements.
10+
11+
This is a documentation/process convention, not a protocol claim — it does not go through the
12+
FACT/HYPOTHESIS/ADR sign-off gate in `AGENTS.md` §6/§15 (that gate governs protocol and architecture
13+
claims, not workflow bookkeeping).
14+
15+
---
16+
17+
## 1. Naming scheme
18+
19+
Each logged session produces a **paired** set of two files, sharing the same number and category:
20+
21+
- `NNNN_CATEGORY_PROMPT_YYYY_MM_DD.md` — the prompt given to the agent.
22+
- `NNNN_CATEGORY_RESULT_YYYY_MM_DD.md` — the agent's resulting output/report.
23+
24+
Both live directly in `ai-sessions/` (no subdirectories).
25+
26+
- **`NNNN`** — a single, global, zero-padded 4-digit sequence number, shared across **all**
27+
categories (e.g. `0001`, `0002`, `0003`, …). There is no separate per-category counter — a
28+
`CROSSCHECK` entry and the next `REVIEW` entry share the same increasing sequence.
29+
- **`CATEGORY`** — one of the fixed values in §2 below.
30+
- **`YYYY_MM_DD`** — the date the prompt was given (for the `PROMPT` file) — the `RESULT` file uses
31+
the same date as its paired `PROMPT` file even if the result itself was finished or last updated
32+
on a later date (the header's `status` field, §4, is where later-date context belongs for a
33+
multi-part result, per §5).
34+
35+
**Example pair:** `ai-sessions/0001_CROSSCHECK_PROMPT_2026_09_07.md` /
36+
`ai-sessions/0001_CROSSCHECK_RESULT_2026_09_07.md`.
37+
38+
## 2. Fixed category vocabulary
39+
40+
A closed list — no ad hoc category names:
41+
42+
| Category | Use for |
43+
|---|---|
44+
| `FEATURE` | Implementing or designing a specific protocol/app feature |
45+
| `CROSSCHECK` | Cross-validating existing findings against captures/APK/another AI model |
46+
| `REVIEW` | Reviewing existing documentation, code, or findings for correctness/consistency |
47+
| `AUDIT` | Broad, structured audits of project state, scope, or compliance with `AGENTS.md`/`PROJECT_RULES.md` |
48+
| `SETUP` | Environment, tooling, or workstation setup tasks |
49+
| `CAPTURE` | Planning or analyzing a Bluetooth HCI capture session |
50+
| `MAINTENANCE` | Repository/documentation housekeeping not covered by the categories above |
51+
52+
If a new task genuinely doesn't fit any of these, that is a reason to **deliberately extend this
53+
list** (add a new row here, in a dedicated documentation change) — never to invent a one-off
54+
category name for a single session's files.
55+
56+
## 3. Numbering discipline
57+
58+
Before assigning `NNNN` to a new session, **check `ai-sessions/INDEX.md` for the next free number**
59+
— this mirrors the same "check the registry before assigning" discipline `id_registry.csv` already
60+
uses for `CAP-NNN`/`ADR-NNN`/Test-IDs (see `README.md`'s documentation table). `ai-sessions/INDEX.md`
61+
is this convention's own, separate registry — it is **not** merged into `id_registry.csv`, which
62+
keeps its existing scope (captures, ADRs, Test-IDs) unchanged.
63+
64+
## 4. Required header block
65+
66+
Every prompt and result file starts with a header block immediately after the title:
67+
68+
```markdown
69+
# NNNN_CATEGORY_PROMPT_YYYY_MM_DD.md — <one-line title>
70+
71+
**Number:** NNNN
72+
**Category:** CATEGORY
73+
**Date:** YYYY-MM-DD
74+
**Title:** <one-line title>
75+
```
76+
77+
`RESULT` files carry one additional required field, **Status**, with one of these three values:
78+
79+
- `complete` — the task finished in one pass, nothing pending.
80+
- `partial — resumed` — the task was interrupted (e.g. a rate limit) and picked up again; the file
81+
documents how far it got.
82+
- `awaiting maintainer sign-off` — the task itself is finished, but its conclusions are proposals
83+
that need maintainer review before anything is promoted into `PROTOCOL.md`/`DECISIONS.md`/etc.
84+
(per `AGENTS.md` §6).
85+
86+
```markdown
87+
**Status:** complete | partial — resumed | awaiting maintainer sign-off
88+
```
89+
90+
## 5. Multi-part results
91+
92+
A long-running or rate-limit-interrupted task does not get a new number each time it resumes.
93+
Instead, the **same** `RESULT` file is progressively appended to across resumptions, and its
94+
header's `Status` field is updated to reflect the current state (`partial — resumed` while still in
95+
progress, `complete` or `awaiting maintainer sign-off` once it finishes). The `PROMPT` file's number
96+
and date stay fixed to the session's original start — it is not rewritten on each resumption.
97+
98+
## 6. Scope — what gets logged
99+
100+
This applies to **substantive** task prompts: the kind of multi-phase, governance-aware prompts this
101+
project already produces for capture analysis, APK reverse-engineering passes, and audits — not
102+
one-off trivial commands (a single file read, a quick grep, a one-line typo fix). Use judgment, but
103+
**default to logging when in doubt** — an unnecessary log entry costs little; a missing one loses a
104+
record of "how this AI-agent output was arrived at" that no chat transcript preserves once the
105+
session ends.
106+
107+
## 7. Version control
108+
109+
These files are **git-tracked**, not gitignored — they are permanent project record, on the same
110+
footing as `CAP-NNN-FINDINGS.md` or `DECISIONS.md`.
111+
112+
---
113+
https://github.com/tedsluis/opencontrolpixelbudspro2/blob/main/AI_SESSION_LOG_PROCEDURE.md - https://tedsluis.github.io/opencontrolpixelbudspro2/AI_SESSION_LOG_PROCEDURE

‎PROJECT_RULES.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,10 @@ document disconnected from the capture it belongs to.
161161
compatibility, coding standards, etc.) at all times, and flags any
162162
request that would conflict with them instead of silently complying.
163163
- uses consistent terminology as defined in `PROTOCOL.md`.
164+
13a. Every substantive AI-agent prompt and its resulting output/report are logged as a paired
165+
`NNNN_CATEGORY_PROMPT_YYYY_MM_DD.md`/`NNNN_CATEGORY_RESULT_YYYY_MM_DD.md` file in
166+
`ai-sessions/` — see `AI_SESSION_LOG_PROCEDURE.md` for the naming scheme, category vocabulary,
167+
numbering discipline, and required header block.
164168

165169
## 6. Reproducibility and technical debt
166170

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,8 @@ humans and AI coding assistants working on it:
140140
| `TODO.md` | Open tasks and current project status |
141141
| `CHANGELOG.md` | Changes per release |
142142
| `id_registry.csv` | Machine-readable registry of every `CAP-NNN`/`ADR-NNN`/Test-ID — check before assigning a new one |
143+
| `AI_SESSION_LOG_PROCEDURE.md` | Naming scheme, category vocabulary, and numbering discipline for logging AI-agent prompts/results into `ai-sessions/` |
144+
| `ai-sessions/INDEX.md` | Registry of every logged AI-agent prompt/result pair under `ai-sessions/` — check before assigning the next number |
143145
| `scripts/lint_docs.py` | Grep-based doc lint (dead filenames, unregistered IDs, stale project name) — run before committing a doc change |
144146

145147
## Target platform

‎ai-sessions/0001_CROSSCHECK_PROMPT_2026_09_07.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 0001_CROSSCHECK_PROMPT_2026_09_07.md — Deep V1-without-GMS iterative cross-check (2nd pass)
2+
3+
**Number:** 0001
4+
**Category:** CROSSCHECK
5+
**Date:** 2026-09-07
6+
**Title:** Deep V1-without-GMS iterative cross-check (2nd pass)
7+
8+
> **Reconstruction note:** `ai-sessions/` and this logging convention (`AI_SESSION_LOG_PROCEDURE.md`)
9+
> did not exist yet when this session ran — its prompt was given directly in a chat conversation and
10+
> was never saved verbatim to a file. This `PROMPT` file is a **reconstruction**, assembled from the
11+
> task instructions the paired `0001_CROSSCHECK_RESULT_2026_09_07.md` file itself quotes, restates,
12+
> and works from throughout (its Phase 0 reading list, its "per this task's instructions"/"per this
13+
> task's own instruction" references, and its Work-plan checklist). It is not a byte-for-byte replay
14+
> of the original prompt text. Entry `0001` is bootstrapped this way, by explicit maintainer
15+
> instruction, so this new system starts from real content instead of an empty registry — later
16+
> entries are logged from the actual prompt text going forward.
17+
18+
---
19+
20+
## Reconstructed task instructions
21+
22+
Perform a deep, iterative re-investigation of the V1-without-GMS scope, cross-checking every
23+
relevant Bluetooth capture against the decompiled companion-app APK source. This is a second, more
24+
thorough pass at what `AUDIT_REPORT_2026-09-07.md` Phase 1 attempted in a rushed, single-pass form
25+
(two of three planned research passes had failed mid-run on a session-wide rate limit; the surviving
26+
pass was a single-pass manual investigation, not the broader iterative search a dedicated pass would
27+
run).
28+
29+
**Operational constraints:**
30+
- Work sequentially, in one continuous session — no parallel sub-agent/Task-tool passes.
31+
- Maintain a running progress file (`DEEP_CROSSCHECK_PROGRESS_2026-09-07.md`), appended after every
32+
phase and after any individually time-consuming step, so a resumed session can read it first and
33+
continue from wherever it stopped, never restarting a phase already checkpointed there.
34+
- **AI-assistance boundary throughout, per `DECISIONS.md` ADR-017:** search, list candidates, and
35+
explain already-surfaced code — never decide relevance, never record a finding directly in
36+
`REVERSE_ENGINEERING.md`, never self-promote anything to 🟢 FACT, never write or amend a
37+
`DECISIONS.md` ADR. Everything produced is a proposal for maintainer review unless explicitly
38+
marked otherwise.
39+
40+
**Required reading order at session start**, per `AGENTS.md` §0.1: `AGENTS.md` (full),
41+
`PROJECT_RULES.md` (full), `PROJECT.md`, `ARCHITECTURE.md`, `PROTOCOL.md` (full, including its
42+
changelog and open items), `DECISIONS.md` (every ADR, ADR-001 through the most recent — with extra
43+
care on the ADRs most relevant to the GMS-boundary/DLCI-0x02 questions this pass investigates),
44+
`TODO.md`. Plus, for this specific task: `REVERSE_ENGINEERING.md` (full), the reverse-engineering
45+
procedure and version-tracking docs, the capture index in `CAPTURE_BLUETOOTH_HCI_SNOOP.md` §9, the
46+
Test-ID catalog, `DESKRESEARCH_FINDINGS.md`, and `id_registry.csv`.
47+
48+
**Work plan — the questions this task needs to answer:**
49+
50+
- **Phase 1 (GMS-boundary Q1–Q3 re-investigation):** go beyond the prior audit pass's keyword-only
51+
grep. Q1: search for any AIDL-generated interface / `Binder`/`ServiceConnection`/callback
52+
interface with an ANC-state/settings-notification-shaped method signature, by structural pattern,
53+
not just keyword. Q2: for any class that only *receives* an already-decoded domain event, trace
54+
its registration/subscription call site to determine which system component it actually registers
55+
with. Q3: check whether `apktool-output/AndroidManifest.xml` declares any binding to a GMS-side
56+
service relevant to this boundary. Produce a per-question verdict.
57+
- **Phase 2 (deepen DLCI 0x02 / `libmaestro` tracing):** trace which `maestro_pw.*` services fire
58+
specifically inside the connect-time burst; trace `frb.java`'s `"primary route change"` callback
59+
further; fully resolve `fsz.java`'s shared-dispatcher structure (trace `WriteSetting`'s actual
60+
caller through the R8-merged-lambda dispatcher rather than leaving it as an acknowledged gap);
61+
trace `qhr` field 13's ANC-write call site trigger; apply ADR-019's static-analysis method to `qhr`
62+
field 11 (Multipoint) and field 15 (Volume EQ), the two fields `TODO.md` explicitly flags as
63+
unchecked.
64+
- **Phase 3 (per-V1-feature confirmation pass):** for every V1-scope feature in `PROJECT.md`'s
65+
functional checklist (battery, ANC, EQ, touch controls, head gestures, firmware/serial, Find My
66+
Buds Left/Right vs. Case/"both", in-ear detection, multipoint, case sounds), state which evidence
67+
is DLCI-0x02/companion-app-code-backed versus DLCI-0x04/0x08/GMS-boundary, incorporating whatever
68+
Phase 1/Phase 2 turn up.
69+
- **Phase 4 (write-up):** draft (as proposals only, per the AI-assistance boundary above) proposed
70+
`PROTOCOL.md` §6 updates, proposed `REVERSE_ENGINEERING.md` updates, proposed `TODO.md`
71+
closures/reprioritizations, and a draft `DECISIONS.md` ADR-025 Update note — none of it committed
72+
directly.
73+
74+
**Deliverable:** the progress file itself, ending with a summary for the maintainer covering what's
75+
now more strongly confirmed, what's newly found, what changed from the previous pass's conclusions,
76+
and what's proposed and awaiting maintainer sign-off.
77+
78+
---
79+
https://github.com/tedsluis/opencontrolpixelbudspro2/blob/main/ai-sessions/0001_CROSSCHECK_PROMPT_2026_09_07.md - https://tedsluis.github.io/opencontrolpixelbudspro2/ai-sessions/0001_CROSSCHECK_PROMPT_2026_09_07

0 commit comments

Comments
 (0)