@@ -18,7 +18,7 @@ crashes, auth failures, broken setups, slow launches, or anything else. Your job
1818find out what went wrong, unblock the user if you can, and turn what you learned into
1919a well written GitHub issue when one is warranted.
2020
21- A triage context file with machine facts (version , OS, paths, server liveness) was
21+ A triage context file with machine facts (versions , OS, paths, server liveness) was
2222provided alongside this playbook. Everything machine-specific lives there, not here.
2323
2424## 1. Ask what went wrong
@@ -30,9 +30,15 @@ valuable thing you can extract from this conversation.
3030
3131## 2. Read the machine facts
3232
33- Read the triage context file before investigating. It tells you the installed
34- version, the OS, whether the server process is currently running, and the exact
35- paths for state, logs, and the database.
33+ Read the triage context file before investigating. It tells you the OS, whether
34+ the server process is currently running, and the exact paths for state, logs, and
35+ the database.
36+
37+ Its triage CLI version (called "Installed version" in older context files) is only
38+ the version of the \`t3\` that ran \`t3 triage\`. It is often not the build the bug
39+ happened on: \`npx t3 triage\` runs whatever \`t3\` npm resolves, while the user may
40+ run the desktop app, the background service, or a nightly. The server process line
41+ gives the local server's version when the server recorded one.
3642
3743## 3. Check for a newer playbook
3844
@@ -42,8 +48,16 @@ instead of this one. The user may be on an old release with an old copy.
4248
4349## 4. Get the source
4450
45- Clone the repo at the tag matching the user's installed version, into the source
46- cache directory named in the context file, one subdirectory per commit hash:
51+ Before cloning, ask the user which version, device, and surface the bug happened
52+ on. The bug may have happened on another machine, a remote server, the mobile app,
53+ or an older build they have since updated. Check their answer against local facts
54+ where they apply: the server version in the context file, or \`serverVersion\` from
55+ \`<origin>/.well-known/t3/environment\` when a local server is running. If neither
56+ the user nor the machine can tell you the version, say it is unknown. Do not guess.
57+
58+ Clone the repo at the release tag for that version (\`v\` followed by the version,
59+ such as \`v0.0.42\`), into the source cache directory named in the context file,
60+ one subdirectory per commit hash:
4761
4862 git clone --depth 1 --filter=blob:none --branch <release-tag> \\
4963 https://github.com/pingdotgg/t3code <source-cache-dir>/<hash>
@@ -94,8 +108,8 @@ comes from this repo's \`main\` branch.
94108
95109Search existing issues in pingdotgg/t3code (use \`gh\`, or the public GitHub search
96110API if \`gh\` is missing or not logged in). Then check whether the problem is already
97- fixed in a release newer than the user's version: compare versions, read release
98- notes and recent commits touching the relevant code.
111+ fixed in a release newer than the version the bug happened on : compare versions,
112+ read release notes and recent commits touching the relevant code.
99113
100114If the user is behind and the fix likely shipped, say so plainly and give them the
101115exact update command for how they run the CLI (the context file records how it was
@@ -117,6 +131,8 @@ of \`main\` for that work, never the tag-pinned diagnosis clone.
117131- Match the structure of the \`via-triage\` issue template
118132 (\`.github/ISSUE_TEMPLATE/via-triage.yml\` in the repo): what happened, diagnosis,
119133 repro steps, environment, evidence, related issues.
134+ - Under Version, give the version the bug happened on from step 4, or say it is
135+ unknown. Name the triage CLI version only as the CLI's.
120136- Label it \`via-triage\`. Use a plain, specific title with no prefix.
121137- Show the user the complete final issue text and get an explicit yes before
122138 posting. Never post without it.
@@ -153,7 +169,7 @@ export const buildTriageLaunchPrompt = (promptFilePath: string) =>
153169export const buildTriageSeedPrompt = ( contextFilePath : string ) => `A T3 Code user is \
154170having a problem with their install and started this session with \`t3 triage\`.
155171
156- Machine facts (version , OS, paths, server liveness) are in the triage context file:
172+ Machine facts (versions , OS, paths, server liveness) are in the triage context file:
157173
158174 ${ contextFilePath }
159175
@@ -166,8 +182,7 @@ ${TRIAGE_PLAYBOOK}`;
166182/** Machine facts for one triage run, pre-formatted so the template stays plain. */
167183export interface TriageContextInput {
168184 readonly generatedAt : string ;
169- readonly version : string ;
170- readonly releaseTag : string ;
185+ readonly cliVersion : string ;
171186 readonly os : string ;
172187 readonly nodeVersion : string ;
173188 readonly launchedAs : string ;
@@ -193,8 +208,7 @@ export const buildTriageContext = (input: TriageContextInput) => `# T3 Code tria
193208
194209Generated by \`t3 triage\` at ${ input . generatedAt } .
195210
196- - Installed version: ${ input . version }
197- - Release tag for this version: ${ input . releaseTag }
211+ - Triage CLI version: ${ input . cliVersion } (the \`t3\` that ran this command; the bug may have happened on another build)
198212- OS: ${ input . os }
199213- Node: ${ input . nodeVersion }
200214- CLI launched as: ${ input . launchedAs }
0 commit comments