Enhance Claude Code skill with real-world usage patterns (#116)
* Update skill installation path and document new features Installation path changes: - Update from ~/.claude/skills/bd to bd-issue-tracking - Matches internal skill name for consistency with other skills Documentation additions: - Add 3 new reference files to documentation list - Document compaction survival patterns (critical for Claude Code) - Mention self-check checklists and quality guidelines This prepares the README for upcoming skill content improvements. * Add new reference files for enhanced skill guidance New reference documentation: 1. ISSUE_CREATION.md - When to ask vs create issues - Decision criteria for knowledge work vs technical work - Issue quality guidelines and best practices - Design vs acceptance criteria guidance - Self-check questions for well-scoped issues 2. RESUMABILITY.md - Making issues resumable across sessions - Patterns for complex technical work with APIs - Working code examples and API response samples - When enhanced documentation matters vs simple descriptions - Critical for multi-session work and crash recovery 3. STATIC_DATA.md - Using bd for reference databases - Alternative use case beyond work tracking - Glossaries and terminology management - Dual format patterns (database + markdown) - When bd helps vs when simpler formats suffice These additions emerged from real-world usage patterns and enable Claude to make better decisions about issue structure and resumability. * Enhance existing skill files with real-world usage patterns SKILL.md major enhancements (~194 net lines added): - Add "Test Yourself" decision framework with self-check questions - Document compaction survival patterns (critical for Claude Code) - Add Notes Quality Self-Check (future-me test, stranger test) - Session Start Checklist with copy-paste templates - Field Usage Reference table (when to use each bd field) - Progress Checkpointing triggers and patterns - Issue Creation Checklist with quality self-checks - Enhanced session handoff protocols WORKFLOWS.md enhancements (~114 lines added): - Session handoff workflow with detailed checklists - Collaborative handoff between Claude and user - Compaction survival workflow - Notes format guidelines (current state, not cumulative) - Session start checklist expansion BOUNDARIES.md updates (~49 lines removed): - Streamlined content (moved detailed workflows to WORKFLOWS.md) - Retained core decision criteria - Improved examples and integration patterns CLI_REFERENCE.md minor updates: - Additional command examples - Clarified flag usage These improvements emerged from extensive real-world usage, particularly around crash recovery, compaction events, and multi-session workflows. The additions make the skill more practical for autonomous agent use.
This commit is contained in:
spm1001
GitHub
@@ -246,55 +246,6 @@ Rare, but happens when bd issue turns out simpler than expected.
|
||||
5. Note: "Completed in single session, simpler than expected"
|
||||
```
|
||||
|
||||
### Pattern 4: Temporal Layering (Complementary Use)
|
||||
|
||||
**Key insight**: TodoWrite and bd operate at different timescales and serve different memory needs.
|
||||
|
||||
**TodoWrite** (short-term working memory - this hour):
|
||||
- Tactical execution steps
|
||||
- Present/future tense ("Implement", "Test", "Deploy")
|
||||
- Marked completed as you go
|
||||
- Ephemeral: Disappears when session ends
|
||||
|
||||
**Beads** (long-term episodic memory - this week/month):
|
||||
- Strategic objectives and context
|
||||
- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
|
||||
- Key decisions and outcomes in notes field
|
||||
- Persistent: Survives compaction and session boundaries
|
||||
|
||||
**The Handoff Pattern:**
|
||||
1. **Session start**: Read bead → Create TodoWrite items for immediate actions
|
||||
2. **During work**: Mark TodoWrite items completed as you go
|
||||
3. **Reach milestone**: Update bead notes with outcomes + context
|
||||
4. **Session end**: TodoWrite disappears, bead survives with enriched notes
|
||||
|
||||
**After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened.
|
||||
|
||||
**Example - TodoWrite tracks execution, Beads capture meaning:**
|
||||
|
||||
TodoWrite for this session:
|
||||
```
|
||||
[completed] Implement login endpoint
|
||||
[in_progress] Add password hashing with bcrypt
|
||||
[pending] Create session middleware
|
||||
```
|
||||
|
||||
Corresponding bead notes:
|
||||
```bash
|
||||
bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
|
||||
hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
|
||||
auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
|
||||
NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."
|
||||
```
|
||||
|
||||
**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
|
||||
|
||||
**When to use this pattern:**
|
||||
- Long-running features requiring multiple sessions
|
||||
- Work that will likely face compaction
|
||||
- Need both immediate visibility (TodoWrite) and long-term memory (bd)
|
||||
- Strategic work with tactical execution steps
|
||||
|
||||
## Real-World Examples
|
||||
|
||||
### Example 1: Database Migration Planning
|
||||
|
||||
@@ -190,13 +190,9 @@ Visualize full dependency tree for an issue.
|
||||
|
||||
```bash
|
||||
bd dep tree issue-123
|
||||
|
||||
# Limit tree depth (default: 50)
|
||||
bd dep tree issue-123 --max-depth 10
|
||||
bd dep tree issue-123 -d 10
|
||||
```
|
||||
|
||||
Shows all dependencies and dependents in tree format. Use `--max-depth` to limit traversal depth for very deep trees.
|
||||
Shows all dependencies and dependents in tree format.
|
||||
|
||||
---
|
||||
|
||||
|
||||
139
examples/claude-code-skill/references/ISSUE_CREATION.md
Normal file
139
examples/claude-code-skill/references/ISSUE_CREATION.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Issue Creation Guidelines
|
||||
|
||||
Guidance on when and how to create bd issues for maximum effectiveness.
|
||||
|
||||
## Contents
|
||||
|
||||
- [When to Ask First vs Create Directly](#when-to-ask)
|
||||
- [Issue Quality](#quality)
|
||||
- [Making Issues Resumable](#resumable)
|
||||
- [Design vs Acceptance Criteria](#design-vs-acceptance)
|
||||
|
||||
## When to Ask First vs Create Directly {#when-to-ask}
|
||||
|
||||
### Ask the user before creating when:
|
||||
- Knowledge work with fuzzy boundaries
|
||||
- Task scope is unclear
|
||||
- Multiple valid approaches exist
|
||||
- User's intent needs clarification
|
||||
|
||||
### Create directly when:
|
||||
- Clear bug discovered during implementation
|
||||
- Obvious follow-up work identified
|
||||
- Technical debt with clear scope
|
||||
- Dependency or blocker found
|
||||
|
||||
**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
|
||||
|
||||
## Issue Quality {#quality}
|
||||
|
||||
Use clear, specific titles and include sufficient context in descriptions to resume work later.
|
||||
|
||||
### Field Usage
|
||||
|
||||
**Use --design flag for:**
|
||||
- Implementation approach decisions
|
||||
- Architecture notes
|
||||
- Trade-offs considered
|
||||
|
||||
**Use --acceptance flag for:**
|
||||
- Definition of done
|
||||
- Testing requirements
|
||||
- Success metrics
|
||||
|
||||
## Making Issues Resumable (Complex Technical Work) {#resumable}
|
||||
|
||||
For complex technical features spanning multiple sessions, enhance notes field with implementation details.
|
||||
|
||||
### Optional but valuable for technical work:
|
||||
- Working API query code (tested, with response structure)
|
||||
- Sample API responses showing actual data
|
||||
- Desired output format examples (show, don't describe)
|
||||
- Research context (why this approach, what was discovered)
|
||||
|
||||
### Example pattern:
|
||||
|
||||
```markdown
|
||||
bd update issue-9 --notes "IMPLEMENTATION GUIDE:
|
||||
WORKING CODE: service.about().get(fields='importFormats')
|
||||
Returns: dict with 49 entries like {'text/markdown': [...]}
|
||||
OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
|
||||
CONTEXT: text/markdown support added July 2024, not in static docs"
|
||||
```
|
||||
|
||||
**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
|
||||
|
||||
**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
|
||||
|
||||
## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
|
||||
|
||||
Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
|
||||
|
||||
### DESIGN field (HOW to build it):
|
||||
- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
|
||||
- "Parse with regex to find * and _ markers"
|
||||
- "Use JWT tokens with 1-hour expiry"
|
||||
- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
|
||||
|
||||
### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
|
||||
- "Bold and italic markdown formatting renders correctly in the Doc"
|
||||
- "Solution accepts markdown input and creates Doc with specified title"
|
||||
- "Returns doc_id and webViewLink to caller"
|
||||
- "User tokens persist across sessions and refresh automatically"
|
||||
|
||||
### Why this matters:
|
||||
- Design can change during implementation (e.g., use library instead of regex)
|
||||
- Acceptance criteria should remain stable across sessions
|
||||
- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
|
||||
- Each criterion should be **verifiable** - you can definitively say yes/no
|
||||
|
||||
### The pitfall
|
||||
|
||||
Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
|
||||
|
||||
Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
|
||||
|
||||
### Test yourself
|
||||
|
||||
If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
|
||||
|
||||
### Example of correct structure
|
||||
|
||||
✅ **Design field:**
|
||||
```
|
||||
Two-phase Docs API approach:
|
||||
1. Parse markdown to positions
|
||||
2. Create doc + insert text in one call
|
||||
3. Apply formatting in second call
|
||||
Rationale: Atomic operations, easier to debug formatting separately
|
||||
```
|
||||
|
||||
✅ **Acceptance criteria:**
|
||||
```
|
||||
- [ ] Markdown formatting renders in Doc (bold, italic, headings)
|
||||
- [ ] Lists preserve order and nesting
|
||||
- [ ] Links are clickable
|
||||
- [ ] Large documents (>50KB) process without timeout
|
||||
```
|
||||
|
||||
❌ **Wrong (design masquerading as criteria):**
|
||||
```
|
||||
- [ ] Use two-phase batchUpdate approach
|
||||
- [ ] Apply formatting in second batchUpdate call
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Creating good issues:**
|
||||
|
||||
1. **Title**: Clear, specific, action-oriented
|
||||
2. **Description**: Problem statement, context, why it matters
|
||||
3. **Design**: Approach, architecture, trade-offs (can change)
|
||||
4. **Acceptance**: Outcomes, success criteria (should be stable)
|
||||
5. **Notes**: Implementation details, session handoffs (evolves over time)
|
||||
|
||||
**Common mistakes:**
|
||||
|
||||
- Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
|
||||
- Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
|
||||
- Missing context: "Update database" → "Update database: add user_last_login for session analytics"
|
||||
207
examples/claude-code-skill/references/RESUMABILITY.md
Normal file
207
examples/claude-code-skill/references/RESUMABILITY.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Making Issues Resumable Across Sessions
|
||||
|
||||
## When Resumability Matters
|
||||
|
||||
**Use enhanced documentation for:**
|
||||
- Multi-session technical features with API integration
|
||||
- Complex algorithms requiring code examples
|
||||
- Features with specific output format requirements
|
||||
- Work with "occult" APIs (undocumented capabilities)
|
||||
|
||||
**Skip for:**
|
||||
- Simple bug fixes with clear scope
|
||||
- Well-understood patterns (CRUD operations, etc.)
|
||||
- Single-session tasks
|
||||
- Work with obvious acceptance criteria
|
||||
|
||||
**The test:** Would a fresh Claude instance (or you after 2 weeks) struggle to resume this work from the description alone? If yes, add implementation details.
|
||||
|
||||
## Anatomy of a Resumable Issue
|
||||
|
||||
### Minimal (Always Include)
|
||||
```markdown
|
||||
Description: What needs to be built and why
|
||||
Acceptance Criteria: Concrete, testable outcomes (WHAT not HOW)
|
||||
```
|
||||
|
||||
### Enhanced (Complex Technical Work)
|
||||
```markdown
|
||||
Notes Field - IMPLEMENTATION GUIDE:
|
||||
|
||||
WORKING CODE:
|
||||
```python
|
||||
# Tested code that queries the API
|
||||
service = build('drive', 'v3', credentials=creds)
|
||||
result = service.about().get(fields='importFormats').execute()
|
||||
# Returns: {'text/markdown': ['application/vnd.google-apps.document'], ...}
|
||||
```
|
||||
|
||||
API RESPONSE SAMPLE:
|
||||
Shows actual data structure (not docs description)
|
||||
|
||||
DESIRED OUTPUT FORMAT:
|
||||
```markdown
|
||||
# Example of what the output should look like
|
||||
Not just "return markdown" but actual structure
|
||||
```
|
||||
|
||||
RESEARCH CONTEXT:
|
||||
Why this approach? What alternatives were considered?
|
||||
Key discoveries that informed the design.
|
||||
```
|
||||
|
||||
## Real Example: Before vs After
|
||||
|
||||
### ❌ Not Resumable
|
||||
```
|
||||
Title: Add dynamic capabilities resources
|
||||
Description: Query Google APIs for capabilities and return as resources
|
||||
Acceptance: Resources return capability info
|
||||
```
|
||||
|
||||
**Problem:** Future Claude doesn't know:
|
||||
- Which API endpoints to call
|
||||
- What the responses look like
|
||||
- What format to return
|
||||
|
||||
### ✅ Resumable
|
||||
```
|
||||
Title: Add dynamic capabilities resources
|
||||
Description: Query Google APIs for system capabilities (import formats,
|
||||
themes, quotas) that aren't in static docs. Makes server self-documenting.
|
||||
|
||||
Notes: IMPLEMENTATION GUIDE
|
||||
|
||||
WORKING CODE (tested):
|
||||
```python
|
||||
from workspace_mcp.tools.drive import get_credentials
|
||||
from googleapiclient.discovery import build
|
||||
|
||||
creds = get_credentials()
|
||||
service = build('drive', 'v3', credentials=creds)
|
||||
about = service.about().get(
|
||||
fields='importFormats,exportFormats,folderColorPalette'
|
||||
).execute()
|
||||
|
||||
# Returns:
|
||||
# - importFormats: dict, 49 entries like {'text/markdown': [...]}
|
||||
# - exportFormats: dict, 10 entries
|
||||
# - folderColorPalette: list, 24 hex strings
|
||||
```
|
||||
|
||||
OUTPUT FORMAT EXAMPLE:
|
||||
```markdown
|
||||
# Drive Import Formats
|
||||
|
||||
Google Drive supports 49 import formats:
|
||||
|
||||
## Text Formats
|
||||
- **text/markdown** → Google Docs ✨ (NEW July 2024)
|
||||
- text/plain → Google Docs
|
||||
...
|
||||
```
|
||||
|
||||
RESEARCH CONTEXT:
|
||||
text/markdown support announced July 2024 but NOT in static Google docs.
|
||||
Google's workspace-developer MCP server doesn't expose this.
|
||||
This is why dynamic resources matter.
|
||||
|
||||
Acceptance Criteria:
|
||||
- User queries workspace://capabilities/drive/import-formats
|
||||
- Response shows all 49 formats including text/markdown
|
||||
- Output is readable markdown, not raw JSON
|
||||
- Queries live API (not static data)
|
||||
```
|
||||
|
||||
**Result:** Fresh Claude instance can:
|
||||
1. See working API query code
|
||||
2. Understand response structure
|
||||
3. Know desired output format
|
||||
4. Implement with context
|
||||
|
||||
## Optional Template
|
||||
|
||||
Copy this into notes field for complex technical features:
|
||||
|
||||
```markdown
|
||||
IMPLEMENTATION GUIDE FOR FUTURE SESSIONS:
|
||||
|
||||
WORKING CODE (tested):
|
||||
```language
|
||||
# Paste actual code that works
|
||||
# Include imports and setup
|
||||
# Show what it returns
|
||||
```
|
||||
|
||||
API RESPONSE SAMPLE:
|
||||
```json
|
||||
{
|
||||
"actualField": "actualValue",
|
||||
"structure": "as returned by API"
|
||||
}
|
||||
```
|
||||
|
||||
DESIRED OUTPUT FORMAT:
|
||||
```
|
||||
Show what the final output should look like
|
||||
Not just "markdown" but actual structure/style
|
||||
```
|
||||
|
||||
RESEARCH CONTEXT:
|
||||
- Why this approach?
|
||||
- What alternatives considered?
|
||||
- Key discoveries?
|
||||
- Links to relevant docs/examples?
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Over-Documenting Simple Work
|
||||
```markdown
|
||||
Title: Fix typo in README
|
||||
Notes: IMPLEMENTATION GUIDE
|
||||
WORKING CODE: Open README.md, change "teh" to "the"...
|
||||
```
|
||||
**Problem:** Wastes tokens on obvious work.
|
||||
|
||||
### ❌ Design Details in Acceptance Criteria
|
||||
```markdown
|
||||
Acceptance:
|
||||
- [ ] Use batchUpdate approach
|
||||
- [ ] Call API with fields parameter
|
||||
- [ ] Format as markdown with ## headers
|
||||
```
|
||||
**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
|
||||
|
||||
### ❌ Raw JSON Dumps
|
||||
```markdown
|
||||
API RESPONSE:
|
||||
{giant unformatted JSON blob spanning 100 lines}
|
||||
```
|
||||
**Problem:** Hard to read. Extract relevant parts, show structure.
|
||||
|
||||
### ✅ Right Balance
|
||||
```markdown
|
||||
API RESPONSE SAMPLE:
|
||||
Returns dict with 49 entries. Example entries:
|
||||
- 'text/markdown': ['application/vnd.google-apps.document']
|
||||
- 'text/plain': ['application/vnd.google-apps.document']
|
||||
- 'application/pdf': ['application/vnd.google-apps.document']
|
||||
```
|
||||
|
||||
## When to Add This Detail
|
||||
|
||||
**During issue creation:**
|
||||
- Already have working code from research? Include it.
|
||||
- Clear output format in mind? Show example.
|
||||
|
||||
**During work (update notes):**
|
||||
- Just got API query working? Add to notes.
|
||||
- Discovered important context? Document it.
|
||||
- Made key decision? Explain rationale.
|
||||
|
||||
**Session end:**
|
||||
- If resuming will be hard, add implementation guide.
|
||||
- If obvious, skip it.
|
||||
|
||||
**The principle:** Help your future self (or next Claude) resume without rediscovering everything.
|
||||
54
examples/claude-code-skill/references/STATIC_DATA.md
Normal file
54
examples/claude-code-skill/references/STATIC_DATA.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Using bd for Static Reference Data
|
||||
|
||||
bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
|
||||
|
||||
## Work Tracking (Primary Use Case)
|
||||
|
||||
Standard bd workflow:
|
||||
- Issues flow through states (open → in_progress → closed)
|
||||
- Priorities and dependencies matter
|
||||
- Status tracking is essential
|
||||
- IDs are sufficient for referencing
|
||||
|
||||
## Reference Databases / Glossaries (Alternative Use)
|
||||
|
||||
When using bd for static data (terminology, glossaries, reference information):
|
||||
|
||||
**Characteristics:**
|
||||
- Entities are mostly static (typically always open)
|
||||
- No real workflow or state transitions
|
||||
- Names/titles more important than IDs
|
||||
- Minimal or no dependencies
|
||||
|
||||
**Recommended approach:**
|
||||
- Use separate database (not mixed with work tracking) to avoid confusion
|
||||
- Consider dual format: maintain markdown version alongside database for name-based lookup
|
||||
- Example: A terminology database could use both `terms.db` (queryable via bd) and `GLOSSARY.md` (browsable by name)
|
||||
|
||||
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
**Good fit:**
|
||||
- Technical glossaries or terminology databases
|
||||
- Reference documentation that needs dependency tracking
|
||||
- Knowledge bases with relationships between entries
|
||||
- Structured data that benefits from queryability
|
||||
|
||||
**Poor fit:**
|
||||
- Data that changes frequently (use work tracking pattern)
|
||||
- Simple lists (markdown is simpler)
|
||||
- Data that needs complex queries (use proper database)
|
||||
|
||||
## Limitations
|
||||
|
||||
**bd show requires IDs, not names:**
|
||||
- `bd show term-42` works
|
||||
- `bd show "API endpoint"` doesn't work
|
||||
- Workaround: `bd list | grep -i "api endpoint"` to find ID first
|
||||
- This is why dual format (bd + markdown) is recommended for reference data
|
||||
|
||||
**No search by content:**
|
||||
- bd searches by ID, title filters, status, labels
|
||||
- For full-text search across descriptions/notes, use grep on the JSONL file
|
||||
- Example: `grep -i "authentication" .beads/issues.jsonl`
|
||||
@@ -11,6 +11,7 @@ Detailed step-by-step workflows for common bd usage patterns with checklists.
|
||||
- [Epic Planning](#epic-planning) - Structuring complex work with dependencies
|
||||
- [Side Quest Handling](#side-quests) - Discovery during main task, assessing blocker vs deferrable, resuming
|
||||
- [Multi-Session Resume](#resume) - Returning after days/weeks away
|
||||
- [Session Handoff Workflow](#session-handoff) - Collaborative handoff between sessions
|
||||
- [Unblocking Work](#unblocking) - Handling blocked issues
|
||||
- [Integration with TodoWrite](#integration-with-todowrite) - Using both tools together
|
||||
- [Common Workflow Patterns](#common-workflow-patterns)
|
||||
@@ -234,6 +235,119 @@ Resume Workflow:
|
||||
|
||||
---
|
||||
|
||||
## Session Handoff Workflow {#session-handoff}
|
||||
|
||||
**Collaborative handoff between sessions using notes field:**
|
||||
|
||||
This workflow enables smooth work resumption by updating beads notes when stopping, then reading them when resuming. Works in conjunction with compaction survival - creates continuity even after conversation history is deleted.
|
||||
|
||||
### At Session Start (Claude's responsibility)
|
||||
|
||||
```
|
||||
Session Start with in_progress issues:
|
||||
- [ ] Run bd list --status in_progress
|
||||
- [ ] For each in_progress issue: bd show <issue-id>
|
||||
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, NEXT
|
||||
- [ ] Report to user with context from notes field
|
||||
- [ ] Example: "workspace-mcp-server-2 is in_progress. Last session:
|
||||
completed tidying. No code written yet. Next step: create
|
||||
markdown_to_docs.py. Should I continue with that?"
|
||||
- [ ] Wait for user confirmation or direction
|
||||
```
|
||||
|
||||
**Pattern**: Notes field is the "read me first" guide for resuming work.
|
||||
|
||||
### At Session End (Claude prompts user)
|
||||
|
||||
When wrapping up work on an issue:
|
||||
|
||||
```
|
||||
Session End Handoff:
|
||||
- [ ] Notice work reaching a stopping point
|
||||
- [ ] Prompt user: "We just completed X and started Y on <issue-id>.
|
||||
Should I update the beads notes for next session?"
|
||||
- [ ] If yes, suggest command:
|
||||
bd update <issue-id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
|
||||
- [ ] User reviews and confirms
|
||||
- [ ] Claude executes the update
|
||||
- [ ] Notes saved for next session's resumption
|
||||
```
|
||||
|
||||
**Pattern**: Update notes at logical stopping points, not after every keystroke.
|
||||
|
||||
### Notes Format (Current State, Not Cumulative)
|
||||
|
||||
```
|
||||
Good handoff note (current state):
|
||||
COMPLETED: Parsed markdown into structured format
|
||||
IN PROGRESS: Implementing Docs API insertion
|
||||
NEXT: Debug batchUpdate call - getting 400 error on formatting
|
||||
BLOCKER: None
|
||||
KEY DECISION: Using two-phase approach (insert text, then apply formatting) based on reference implementation
|
||||
|
||||
Bad handoff note (not useful):
|
||||
Updated some stuff. Will continue later.
|
||||
```
|
||||
|
||||
**Rules for handoff notes:**
|
||||
- Current state only (overwrite previous notes, not append)
|
||||
- Specific accomplishments (not vague progress)
|
||||
- Concrete next step (not "continue working")
|
||||
- Optional: Blockers, key decisions, references
|
||||
- Written for someone with zero conversation context
|
||||
|
||||
### Session Handoff Checklist
|
||||
|
||||
For Claude at session end:
|
||||
|
||||
```
|
||||
Session End Checklist:
|
||||
- [ ] Work reaching logical stopping point
|
||||
- [ ] Prompt user about updating notes
|
||||
- [ ] If approved:
|
||||
- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
|
||||
- [ ] Include blocker if stuck
|
||||
- [ ] Include key decisions if relevant
|
||||
- [ ] Suggest bd update command
|
||||
- [ ] Execute approved update
|
||||
- [ ] Confirm: "Saved handoff notes for next session"
|
||||
```
|
||||
|
||||
For user (optional, but helpful):
|
||||
|
||||
```
|
||||
User Tips:
|
||||
- [ ] When stopping work: Let Claude suggest notes update
|
||||
- [ ] When resuming: Let Claude read notes and report context
|
||||
- [ ] Avoid: Trying to remember context manually (that's what notes are for!)
|
||||
- [ ] Trust: Well-written notes will help next session pick up instantly
|
||||
```
|
||||
|
||||
### Example: Real Session Handoff
|
||||
|
||||
**Scenario:** Implementing markdown→Docs feature (workspace-mcp-server-2)
|
||||
|
||||
**At End of Session 1:**
|
||||
```bash
|
||||
bd update workspace-mcp-server-2 --notes "COMPLETED: Set up skeleton with Docs
|
||||
API connection verified. Markdown parsing logic 80% done (handles *, _ modifiers).
|
||||
IN PROGRESS: Testing edge cases for nested formatting. NEXT: Implement
|
||||
batchUpdate call structure for text insertion. REFERENCE: Reference pattern at
|
||||
docs/markdown-to-docs-reference.md. No blockers, moving well."
|
||||
```
|
||||
|
||||
**At Start of Session 2:**
|
||||
```bash
|
||||
bd show workspace-mcp-server-2
|
||||
# Output includes notes field showing exactly where we left off
|
||||
# Claude reports: "Markdown→Docs feature is 80% parsed. We were testing
|
||||
# edge cases and need to implement batchUpdate next. Want to continue?"
|
||||
```
|
||||
|
||||
Session resumes instantly with full context, no history scrolling needed.
|
||||
|
||||
---
|
||||
|
||||
## Unblocking Work {#unblocking}
|
||||
|
||||
**When ready list is empty:**
|
||||
|
||||
Reference in New Issue
Block a user