Refresh a Linear issue to align with current docs and code state. Use when user types /refresh-issue BT-XX or asks to refresh/sync an issue with the codebase.
When activated with a Linear issue ID (e.g., /refresh-issue BT-34), execute this workflow to ensure the issue accurately reflects the current state of the codebase.
Issues can become stale as the codebase evolves. This skill:
Use the same resolution logic as pick-issue step 1:
/refresh-issue BT-42 or /refresh-issue 42/workspaces/BT-34 → BT-34)BT-10-implement-lexer → )BT-10Get the full issue details from Linear:
streamlinear-cli get BT-XX
Note the following from the issue:
Check relevant documentation files to ensure the issue aligns with current specs:
| Area | Documentation to Check |
|---|---|
| Language features | docs/beamtalk-language-features.md, docs/beamtalk-syntax-rationale.md |
| Architecture | docs/beamtalk-architecture.md |
| BEAM interop | docs/beamtalk-beam-interop.md |
| Design principles | docs/beamtalk-principles.md |
| Agent guidelines | AGENTS.md |
Compare the issue's requirements against the documentation:
For each file mentioned in "Files to Modify" or related to the issue:
view or glob to locate the filedocs/beamtalk-ddd-model.md. If the issue uses outdated domain terms, flag them for update.Key directories by area:
crates/beamtalk-core/src/source_analysis/crates/beamtalk-core/src/ast.rscrates/beamtalk-core/src/codegen/runtime/apps/beamtalk_runtime/src/lib/crates/beamtalk-cli/crates/beamtalk-core/src/semantic_analysis/Determine if the issue is:
| Status | Criteria | Action |
|---|---|---|
| Already Fixed | Code exists, tests pass, feature works | Mark as Done with comment explaining |
| Partially Fixed | Some acceptance criteria met | Update description noting what's done |
| Still Open | No implementation exists | Update description if needed |
| Obsolete | Requirements changed, no longer needed | Mark as Canceled with explanation |
| Blocked | Depends on unfinished work | Update state to Blocked, add blocking issues |
Based on findings, update the issue appropriately:
streamlinear-cli update BT-XX --state Done
streamlinear-cli comment BT-XX "## Issue Review
**Status**: Already implemented
**Evidence**:
- [describe where the implementation exists]
- [reference specific files/lines]
- [mention relevant tests]
Marking as Done."
Add a comment summarising findings:
streamlinear-cli comment BT-XX "## Issue Review
**Status**: Still open, description updated
**Documentation Review**:
- [note any spec changes or clarifications]
**Code Review**:
- [note current state of relevant code]
- [identify any partial implementations]
**Updated Acceptance Criteria**:
- [list any changes to criteria]
**Files to Modify** (updated):
- [current list of relevant files]"
If the description body needs significant updates (requires GraphQL since CLI update doesn't support body):
# First get the issue UUID
streamlinear-cli get BT-XX
# Then update body via GraphQL
streamlinear-cli graphql "mutation { issueUpdate(id: \"<issue-uuid>\", input: { description: \"[Updated description with current context, acceptance criteria, and file list]\" }) { success } }"
streamlinear-cli update BT-XX --state "Backlog"
# Labels require GraphQL — get label UUIDs first, then apply keeping existing labels
streamlinear-cli graphql "mutation { issueUpdate(id: \"<issue-uuid>\", input: { labelIds: [\"<blocked-uuid>\", \"<existing-area-uuid>\", \"<existing-type-uuid>\"] }) { success } }"
streamlinear-cli comment BT-XX "## Issue Review
**Status**: Blocked
**Blocking Issues**:
- BT-YY: [description of dependency]
Moving to Backlog with blocked label until dependencies are resolved."
streamlinear-cli update BT-XX --state "Canceled"
streamlinear-cli comment BT-XX "## Issue Review
**Status**: Obsolete
**Reason**:
- [explain why this is no longer needed]
- [reference any spec changes or superseding issues]
Marking as Canceled."
Always use this structure for the review comment:
## Issue Review
**Status**: [Already implemented | Still open | Blocked | Obsolete]
**Documentation Review**:
- [Findings from doc review]
**Code Review**:
- [Findings from code review]
- [List any existing implementations]
- [Note any partial progress]
**Acceptance Criteria Status**:
- [x] Criteria that are done
- [ ] Criteria still pending
**Recommendations**:
- [Any suggested changes to scope, approach, or priority]
**Files to Modify** (verified):
- [Current accurate list of files]
/update-issue BT-42
[Agent finds the feature is already implemented]
Comment:
## Issue Review
**Status**: Already implemented
**Documentation Review**:
- Feature matches spec in docs/beamtalk-language-features.md
**Code Review**:
- Implementation exists in crates/beamtalk-core/src/source_analysis/lexer.rs:145-203
- Tests added in crates/beamtalk-core/src/source_analysis/parser/mod.rs
- Snapshot tests in test-package-compiler/cases/lexer/
**Acceptance Criteria Status**:
- [x] Tokenize identifiers
- [x] Tokenize keywords
- [x] Include source spans
Marking as Done.
/update-issue BT-55
[Agent finds description is outdated]
Comment:
## Issue Review
**Status**: Still open, description updated
**Documentation Review**:
- docs/beamtalk-language-features.md was updated to include new block syntax
- Issue description references old syntax style
**Code Review**:
- No implementation exists yet
- Related parsing infrastructure in place at crates/beamtalk-core/src/source_analysis/
**Updated Acceptance Criteria**:
- Added: Support new block parameter syntax `[:x :y |]`
- Removed: Old cascade syntax (moved to separate issue)
**Files to Modify** (verified):
- crates/beamtalk-core/src/source_analysis/lexer.rs
- crates/beamtalk-core/src/source_analysis/parser/mod.rs
- crates/beamtalk-core/src/ast.rs
blocked but keep area/type labels)