refactor: rename Recap back to Trace for AI model comprehension#443
Merged
anandgupta42 merged 3 commits intomainfrom Mar 24, 2026
Merged
refactor: rename Recap back to Trace for AI model comprehension#443anandgupta42 merged 3 commits intomainfrom
anandgupta42 merged 3 commits intomainfrom
Conversation
AI models (Claude, GPT, etc.) struggle to understand "compare recaps" but natively understand "compare traces" — `trace` is standard observability terminology. This reverts the Tracer→Recap rename while keeping backward- compat aliases for both `Tracer` and `Recap`. **Source code (7 files):** - Class `Recap` → `Trace` in `tracing.ts` with backward-compat aliases - CLI command `recap` → `trace` with `recap` kept as hidden alias - TUI slash command `/recap` → `/trace` with `recap` kept as alias - Viewer branding: "Altimate Recap" → "Altimate Trace" - All variable/function names updated (`sessionRecaps` → `sessionTraces`, etc.) **Documentation (7 files):** - `docs/configure/recap.md` → `docs/configure/trace.md` - All doc references updated: CLI, TUI, CI/headless guides - Image directory `assets/images/recap/` → `assets/images/trace/` **Tests (12 files):** - All imports updated `Recap` → `Trace` - Variable shadowing fixed: `const trace: TraceFile` → `const traceFile` Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
This repository is configured for manual code reviews. Comment @claude review to trigger a review.
Tip: disable this comment in your organization's Code Review settings.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
✅ Files skipped from review due to trivial changes (6)
📝 WalkthroughWalkthroughThis PR renames the observability feature terminology from "Recap" back to "Trace" across docs, CLI, TUI, viewer, core observability code, and tests, and adds backward-compatible aliases to preserve existing API compatibility. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
packages/opencode/test/altimate/tracing-display-crash.test.ts (1)
2-2: Top-level comment wording can be clearer.“traceFile list display” reads like an implementation detail; “trace list display” is cleaner documentation wording.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/opencode/test/altimate/tracing-display-crash.test.ts` at line 2, Update the top-level test file comment to use clearer wording: replace "traceFile list display" with "trace list display" in the file's header comment so it documents the test purpose more cleanly; locate the comment at the top of packages/opencode/test/altimate/tracing-display-crash.test.ts and change that phrase while preserving the rest of the sentence (e.g., "Tests for trace list display, title handling, formatting utilities, ...").packages/opencode/test/altimate/tracing-adversarial-snapshot.test.ts (1)
7-7: Prefer “trace viewer” in prose comments.“live traceFile viewer” reads like an internal variable name rather than user-facing terminology; “live trace viewer” is clearer.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/opencode/test/altimate/tracing-adversarial-snapshot.test.ts` at line 7, Update the prose comment that currently says "live traceFile viewer" to use the user-facing term "live trace viewer" instead; search for the exact phrase "live traceFile viewer" (or similar occurrences of "traceFile" in comments) and replace it with "live trace viewer" so the comment reads clearly as user-facing text.packages/opencode/test/altimate/tracing-e2e.test.ts (1)
6-11: Comment text reads awkwardly with variable-style wording.Consider “trace file” and “trace viewer” in the header comments for readability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/opencode/test/altimate/tracing-e2e.test.ts` around lines 6 - 11, The header comment enumerating test goals uses variable-style terms like "traceFile" and "traceFile viewer server" which read awkwardly; update the phrasing to use natural language (e.g., "trace file" and "trace viewer") consistently across the header so items such as "The traceFile file is valid..." and "The traceFile viewer server works correctly" become "The trace file is valid and complete at every point" and "The trace viewer server works correctly" to improve readability and consistency.packages/opencode/test/altimate/tracing-de-attributes.test.ts (1)
2-2: Consider simplifying the docstring wording.“traceFile attributes” can be read as a variable name; “trace file attributes” is clearer.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/opencode/test/altimate/tracing-de-attributes.test.ts` at line 2, Update the top-of-file docstring/comment that currently reads "Tests for data engineering domain-specific traceFile attributes." to use clearer wording "trace file attributes" (i.e., change "traceFile attributes" → "trace file attributes") so the phrase isn't interpreted as a variable name; edit the header comment in tracing-de-attributes.test.ts accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/opencode/src/cli/cmd/tui/app.tsx`:
- Around line 42-45: getTraceViewerUrl currently pins traceViewerTracesDir only
when traceViewerServer is first created, so subsequent calls with a new
tracesDir still generate URLs pointing at the old directory; to fix, always
update traceViewerTracesDir = Trace.getTracesDir(tracesDir) at the start of
getTraceViewerUrl (before creating/returning the URL) so the server uses the
latest path on every call and apply the same change where similar logic appears
(references: getTraceViewerUrl, traceViewerTracesDir, traceViewerServer,
Trace.getTracesDir).
In `@packages/opencode/src/cli/cmd/tui/worker.ts`:
- Around line 50-54: startEventStream() can be called multiple times (e.g., on
rpc.setWorkspace) but per-session state stored in sessionTraces and
sessionUserMsgIds is never cleared, causing stale traces to leak across stream
restarts; update startEventStream() (or the restart path) to reset per-session
state by calling sessionTraces.clear() and sessionUserMsgIds.clear() (and
reinitialize any related counters or limits like MAX_TRACES handling if
applicable) before establishing the new stream so each session starts with a
clean trace state.
---
Nitpick comments:
In `@packages/opencode/test/altimate/tracing-adversarial-snapshot.test.ts`:
- Line 7: Update the prose comment that currently says "live traceFile viewer"
to use the user-facing term "live trace viewer" instead; search for the exact
phrase "live traceFile viewer" (or similar occurrences of "traceFile" in
comments) and replace it with "live trace viewer" so the comment reads clearly
as user-facing text.
In `@packages/opencode/test/altimate/tracing-de-attributes.test.ts`:
- Line 2: Update the top-of-file docstring/comment that currently reads "Tests
for data engineering domain-specific traceFile attributes." to use clearer
wording "trace file attributes" (i.e., change "traceFile attributes" → "trace
file attributes") so the phrase isn't interpreted as a variable name; edit the
header comment in tracing-de-attributes.test.ts accordingly.
In `@packages/opencode/test/altimate/tracing-display-crash.test.ts`:
- Line 2: Update the top-level test file comment to use clearer wording: replace
"traceFile list display" with "trace list display" in the file's header comment
so it documents the test purpose more cleanly; locate the comment at the top of
packages/opencode/test/altimate/tracing-display-crash.test.ts and change that
phrase while preserving the rest of the sentence (e.g., "Tests for trace list
display, title handling, formatting utilities, ...").
In `@packages/opencode/test/altimate/tracing-e2e.test.ts`:
- Around line 6-11: The header comment enumerating test goals uses
variable-style terms like "traceFile" and "traceFile viewer server" which read
awkwardly; update the phrasing to use natural language (e.g., "trace file" and
"trace viewer") consistently across the header so items such as "The traceFile
file is valid..." and "The traceFile viewer server works correctly" become "The
trace file is valid and complete at every point" and "The trace viewer server
works correctly" to improve readability and consistency.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 535e44ed-19d5-4342-bfc8-02b1825ef7b8
⛔ Files ignored due to path filters (2)
docs/docs/assets/images/trace/summary-full.pngis excluded by!**/*.pngdocs/docs/assets/images/trace/summary-tab.pngis excluded by!**/*.png
📒 Files selected for processing (27)
CHANGELOG.mdREADME.mddocs/docs/configure/trace.mddocs/docs/data-engineering/guides/ci-headless.mddocs/docs/usage/ci-headless.mddocs/docs/usage/cli.mddocs/docs/usage/tui.mddocs/mkdocs.ymlpackages/opencode/src/altimate/observability/tracing.tspackages/opencode/src/altimate/observability/viewer.tspackages/opencode/src/cli/cmd/trace.tspackages/opencode/src/cli/cmd/tui/app.tsxpackages/opencode/src/cli/cmd/tui/component/dialog-trace-list.tsxpackages/opencode/src/cli/cmd/tui/worker.tspackages/opencode/src/index.tspackages/opencode/test/altimate/tracing-adversarial-2.test.tspackages/opencode/test/altimate/tracing-adversarial-final.test.tspackages/opencode/test/altimate/tracing-adversarial-snapshot.test.tspackages/opencode/test/altimate/tracing-adversarial.test.tspackages/opencode/test/altimate/tracing-de-attributes.test.tspackages/opencode/test/altimate/tracing-display-crash.test.tspackages/opencode/test/altimate/tracing-e2e.test.tspackages/opencode/test/altimate/tracing-final-audit.test.tspackages/opencode/test/altimate/tracing-integration.test.tspackages/opencode/test/altimate/tracing-persistence.test.tspackages/opencode/test/altimate/tracing-thorough.test.tspackages/opencode/test/altimate/tracing.test.ts
- Keep `traceViewerTracesDir` in sync on every URL request, not just
on first server creation (app.tsx)
- Reset per-session trace state (`sessionTraces`, `sessionUserMsgIds`)
when restarting the event stream in worker.ts
- Fix "traceFile" variable-style wording in test file comments to use
natural language ("trace file", "trace viewer", "trace list")
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Renames "Recap" back to "Trace" across the entire codebase (source, tests, docs, viewer). AI models natively understand "trace" as standard observability terminology but struggle with the non-standard "recap" — users reported that "compare recaps" confuses models while "compare traces" works perfectly.
29 files changed across:
Recap→Trace, CLI commandrecap→trace, TUI/recap→/trace, viewer brandingrecap.md→trace.md, all doc references, image directory renamedBackward-compat aliases preserved:
Tracer,Recapboth point toTrace. CLIrecapand TUI/recapkept as hidden aliases.Type of change
Issue for this PR
Closes #442
How did you verify your code works?
turbo typecheck— 5/5 packages)bun run script/upstream/analyze.ts --markers --base main --strict)Tracer,Recapexports, CLIrecapalias, TUI/recapaliasChecklist
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Refactor
trace//trace(examples:altimate trace list/view).Chores