Skip to content

Commit 333d9a6

Browse files
migmartrimigmartri
committed
docs(specs): add spec 003 for spec capture during the session
Refs #3515 Assisted-by: Claude Code Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev> Chainloop-Trace-Sessions: 4737da59-9559-43a7-b1b0-ede018375481
1 parent c258f1e commit 333d9a6

1 file changed

Lines changed: 120 additions & 0 deletions

File tree

‎docs/specs/003-spec-capture-during-session.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
owner: migmartri
3+
ticket: https://github.com/chainloop-dev/chainloop/issues/3515
4+
prd:
5+
---
6+
7+
# Spec 003: Spec capture during the session
8+
9+
## Summary
10+
This spec changes the spec capture of [Spec 002](002-session-spec-capture.md). It does not replace it. Today the agent captures the spec only at session start. It also captures the user prompt, which the transcript already holds. With this change, the agent does not capture the user's request prompt, because the transcript holds it. A short reminder at each user turn tells the agent to capture a new spec or image from the user. It also tells the agent to capture a changed spec again. The limit on spec files for each session goes from 10 to 25.
11+
12+
## Problem
13+
- The agent captures the user prompt as a spec of kind `text`. The prompt is the first message of the transcript, so the spec material adds no information. The spec list then shows a duplicate as if it were external context.
14+
- The agent receives the capture instruction only at session start. The push does not record a spec that the session creates or changes later. Example: the agent writes a design note in a local notes folder outside the repository. It edits the note many times, and subagents use it as their plan. The evidence does not hold this note, but it holds the prompt and the screenshots.
15+
- A resumed session gets no instruction when the spec folder already holds a file.
16+
- The limit of 10 files keeps the oldest files. In a long session, a spec added late is the first one that the push drops.
17+
18+
## Goals and Non-Goals
19+
- Goal: the spec materials of a session do not hold the user's request prompt.
20+
- Goal: the evidence holds each spec or image that the user gives after the start. It holds each changed spec with its content at push time.
21+
- Goal: the reminder is short and narrow, so that it does not overload the session.
22+
- Goal: the agent still decides what a spec is, as Spec 002 decided (D-001 of Spec 002).
23+
- Non-goal: a list of known spec locations, or rules in the CLI that decide if a file is a spec.
24+
- Non-goal: a new attestation when only the specs changed. A push records new specs only with a new AI-assisted commit, as today.
25+
- Non-goal: a spec for a push after the session ends. Spec 002 accepted this loss, and this spec keeps it.
26+
- Non-goal: changes to the materials, the redaction, or the storage that Spec 002 defines.
27+
28+
## Requirements
29+
30+
### R-001: No request prompt
31+
The capture instruction MUST tell the agent not to capture the user's request prompt. A spec that the user pastes, for example ticket text or a design document, is still a spec. The agent MUST still use kind `text` for a plan that the session approved.
32+
- Done when: a session that starts from a one-line prompt and no other source pushes no spec material.
33+
34+
### R-002: Reminder at each user turn
35+
The system MUST give the agent a short capture reminder at each user prompt, in each agent that has a channel for it. The reminder MUST include the absolute path of the session folder.
36+
- Done when: a resumed session receives the reminder at its next user prompt, also when the folder already holds files.
37+
38+
### R-003: Three cases only
39+
The reminder MUST tell the agent to capture in these cases only:
40+
- The user pastes or gives a new spec.
41+
- The user pastes or gives an image.
42+
- A spec changes, also when the session itself edits it.
43+
44+
For a changed spec, the agent MUST overwrite its spec file with the current content. A local document has its local path as the source address.
45+
- Done when: a session writes a design note outside the working tree and works from it. The push records that note as a `document` spec with its final content.
46+
47+
### R-004: Higher file limit
48+
The push MUST record at most 25 spec files for each session. When there are more, it MUST keep the oldest files and record a warning, as Spec 002 does today.
49+
50+
## Constraints
51+
- The repository is public. The instruction and the reminder text are visible to all users.
52+
- The reminder goes into the agent context at each turn. It must stay short, so that it costs few tokens and does not distract the agent from the task.
53+
- Each agent has its own hook channels. An agent without a channel for the prompt-submit event gets only the session-start instruction.
54+
55+
## Proposal
56+
The user does nothing new.
57+
58+
At session start, the trace hook gives the full capture instruction, as in Spec 002. The instruction no longer lists "a written prompt" as a source. It tells the agent that the transcript already holds the conversation, so a prompt is not a spec. Kind `text` stays for a plan that the user approved in the session and for spec text that came from outside the conversation.
59+
60+
At each user prompt, the trace hook adds a short reminder to the agent context. The reminder names the session folder and covers three cases. When the user pastes or gives a new spec, copy it. When the user pastes or gives an image, copy it. When a spec changes, copy it again. The reminder says nothing else. A spec that the session writes, for example a design note in a local notes folder, is a spec that changes. Its local path is the source address. The push records the content on disk at push time, so the final version of a plan replaces its drafts.
61+
62+
The reminder replaces the old rule that gave the session-start instruction only while the folder was empty. A resumed session gets the reminder at its first user prompt, so it does not need the full instruction again.
63+
64+
The push keeps the rules of Spec 002, with a limit of 25 files instead of 10. A push with no new AI-assisted commits still sends no attestation. The next AI-assisted commit records a spec that the agent added after the last push. The session-end hook still deletes the folder.
65+
66+
Each agent receives the reminder through its own channel:
67+
68+
| Agent | Channel at each user prompt |
69+
|-------|-----------------------------|
70+
| Claude Code | The additional context of the prompt-submit hook response. |
71+
| Cursor | None today. The agent gets the session-start instruction only (D-008). |
72+
| OpenCode | The Chainloop plugin adds a context-only message, as it does at session start. |
73+
74+
```mermaid
75+
sequenceDiagram
76+
actor User
77+
participant Agent as Coding agent
78+
participant Hook as Trace hook or plugin
79+
participant Folder as Session folder
80+
participant CLI as Trace push
81+
82+
User->>Agent: Start session with a task
83+
Agent->>Hook: Session start event
84+
Hook-->>Agent: Full capture instruction (no prompt capture)
85+
Agent->>Folder: Write ticket, documents, images
86+
loop Each user turn
87+
User->>Agent: Prompt
88+
Agent->>Hook: Prompt submit event
89+
Hook-->>Agent: Short reminder with folder path
90+
Note over User,Agent: New spec or image, or a spec changes
91+
Agent->>Folder: Copy it, or overwrite its file
92+
end
93+
User->>CLI: git push
94+
CLI->>Folder: Read up to 25 spec files
95+
CLI->>CLI: Redact, upload, reference (as in Spec 002)
96+
```
97+
98+
## Decision Record
99+
100+
| ID | Decision | Choice | Why (and what we rejected) | Source |
101+
|----|----------|--------|----------------------------|--------|
102+
| D-001 | Capture of a user prompt | Do not capture the user's request prompt. Capture a spec that the user pastes | The transcript is already part of the session evidence, so the spec material is a duplicate. Rejected: keep it and label it "prompt" in the user interface (more data and UI work for no new information). | drafting |
103+
| D-002 | How the system finds specs after session start | A short reminder at each user prompt, with three cases: a new spec, a new image, a changed spec. The agent decides what a spec is | Simple, and it keeps D-001 of Spec 002. It covers resumed sessions. Three narrow cases keep the reminder short, so it does not overload the session. Rejected: a general rule to capture anything that looks like a spec (too much capture). Rejected: a list of known spec locations that a hook watches (a new configuration, and it misses specs at other paths). Rejected: the hook copies matching files itself (the CLI decides what a spec is, and captures noise). Rejected: a check at push time against the transcript (needs transcript analysis for each agent). Rejected: a reminder after each Markdown write (misses a spec that the agent only reads, and more hook logic). | drafting |
104+
| D-003 | A spec added after the last push, with no new AI-assisted commit | Record it with the next AI-assisted commit, as today | An attestation with no new commit is a duplicate of the session. Rejected: push a new attestation when the set of spec digests changed. | drafting |
105+
| D-004 | A push after the session ends | No change: the session-end hook deletes the folder, and that push holds no spec | Accepted in Spec 002. Rejected: keep the folder until the next push, with an age limit (state to track and clean for a rare case). | drafting |
106+
| D-005 | Spec file limit | Raise from 10 to 25 and keep the oldest files | The reminder makes more spec files likely in a long session. The oldest files are the sources the session started from. Rejected: keep the newest files (the start ticket can drop). | drafting |
107+
| D-006 | Relation to Spec 002 | This spec changes Spec 002 and does not supersede it | Most of the capture design does not change. | drafting |
108+
| D-007 | Control of overcapture from the reminder | Measure the number of spec files for each session after release. Make the reminder narrower if the number grows | The three cases are already narrow. Data from real sessions shows if more limits are necessary. | drafting |
109+
| D-008 | Cursor | The session-start instruction only, until Cursor documents a channel that adds context at prompt submit | No channel to use today. | drafting |
110+
111+
## Open Questions
112+
None.
113+
114+
## Risks
115+
116+
| Risk | Mitigation |
117+
|------|------------|
118+
| The agent ignores the reminder, as it ignored the instruction to add a file when the task changed. | The reminder comes at each turn, near the work, and not only at session start. The capture rate of Spec 002 (R-010) stays measurable. |
119+
| A spec written and pushed in the same turn is not captured, because the next reminder comes later. | The session-start instruction still says to update the folder when the task changes. The next push with a new commit records it. |
120+
| The reminder adds tokens to each turn. | Keep it to a few lines. The full instruction stays at session start only. |

0 commit comments

Comments
 (0)