0fcac18357
- Add blog post: 4 Essential Slash Commands I Use in Every Project - Add new slash commands: /doc-refactor, /setup-ci-cd, /unit-test-expand - Update slash-commands README with comprehensive documentation - Simplify /push-all command structure - Archive add-blog-post-slash-commands change - Add blog-post spec and pending openspec changes
107 lines
5.4 KiB
Markdown
107 lines
5.4 KiB
Markdown
# hooks-documentation Spec Delta
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Pre-Message and Post-Response Hook Pairs Documentation
|
|
The hooks lesson SHALL document how to use `UserPromptSubmit` and `Stop` hooks together for context/token usage tracking.
|
|
|
|
#### Scenario: Understanding hook event timing for context tracking
|
|
- **WHEN** a user wants to track per-request token consumption
|
|
- **THEN** they find documentation explaining that `UserPromptSubmit` fires before the prompt is processed (pre-message)
|
|
- **AND** they find documentation explaining that `Stop` fires after Claude completes its response (post-response)
|
|
- **AND** they understand how to calculate the delta between these two points
|
|
|
|
#### Scenario: Token delta calculation methodology
|
|
- **WHEN** a user implements a context tracking hook pair
|
|
- **THEN** they find documentation explaining how to:
|
|
- Record token count at `UserPromptSubmit` time
|
|
- Calculate new token count at `Stop` time
|
|
- Compute the delta representing per-request consumption
|
|
|
|
### Requirement: Context Tracking Hook Pair Example
|
|
The hooks lesson SHALL provide a working example script that tracks context usage using pre-message and post-response hooks.
|
|
|
|
#### Scenario: Single script handles both hook events
|
|
- **WHEN** a user copies the context-tracker.py example
|
|
- **THEN** the script detects the hook event type via `hook_event_name`
|
|
- **AND** handles `UserPromptSubmit` by saving current token estimate to a temp file
|
|
- **AND** handles `Stop` by loading the saved count, calculating delta, and reporting usage
|
|
|
|
#### Scenario: Complete configuration for hook pair
|
|
- **WHEN** a user wants to configure both hooks
|
|
- **THEN** they find a complete settings.json example showing:
|
|
- `UserPromptSubmit` hook configuration pointing to the context tracker script
|
|
- `Stop` hook configuration pointing to the same script
|
|
- Both hooks using the same script for consistent token calculation
|
|
|
|
#### Scenario: Per-request usage reporting
|
|
- **WHEN** the context tracking hooks execute
|
|
- **THEN** the Stop hook outputs a report showing:
|
|
- Total estimated tokens used in session
|
|
- Tokens consumed by the current request (delta)
|
|
- Remaining capacity estimate
|
|
|
|
### Requirement: Token Counting Methods Documentation
|
|
The hooks lesson SHALL document two offline token counting methods that require no API key.
|
|
|
|
#### Scenario: tiktoken-based token counting documented
|
|
- **WHEN** a user wants more accurate offline token counts
|
|
- **THEN** they find documentation for using `tiktoken` with `p50k_base` encoding
|
|
- **AND** they see a Python example using `tiktoken.get_encoding("p50k_base")`
|
|
- **AND** they understand it provides ~90-95% accuracy compared to Claude's tokenizer
|
|
- **AND** they learn it requires the `tiktoken` dependency
|
|
|
|
#### Scenario: Character estimation token counting documented
|
|
- **WHEN** a user wants zero-dependency token estimation
|
|
- **THEN** they find documentation for the ~4 characters per token estimation ratio
|
|
- **AND** they understand this provides ~80-90% accuracy for English text
|
|
- **AND** they learn it works with no external dependencies
|
|
|
|
#### Scenario: Method comparison provided
|
|
- **WHEN** a user needs to choose between token counting methods
|
|
- **THEN** they find a comparison showing:
|
|
- tiktoken method: ~90-95% accuracy, requires tiktoken, <10ms latency
|
|
- Estimation method: ~80-90% accuracy, no dependencies, <1ms latency
|
|
- **AND** both methods work completely offline without API keys
|
|
|
|
#### Scenario: Transcript contents explained
|
|
- **WHEN** a user wants to understand what's included in token counts
|
|
- **THEN** they find documentation explaining that the transcript includes:
|
|
- User prompts
|
|
- Claude's responses
|
|
- Tool inputs and outputs
|
|
- **AND** they understand that system prompts and internal context are NOT included
|
|
|
|
#### Scenario: No official Claude tokenizer caveat
|
|
- **WHEN** a user reads about token counting accuracy
|
|
- **THEN** they understand that Anthropic hasn't released an official offline tokenizer
|
|
- **AND** they understand both methods are approximations based on similar BPE tokenizers
|
|
|
|
## MODIFIED Requirements
|
|
|
|
### Requirement: Context Usage Reporting Hook Example
|
|
The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.
|
|
|
|
#### Scenario: Token calculation is correct
|
|
- **WHEN** a user copies the context-usage.py example
|
|
- **AND** runs it as a Stop hook
|
|
- **THEN** the hook correctly calculates estimated tokens from total character count
|
|
- **AND** displays a non-zero token count proportional to conversation length
|
|
|
|
#### Scenario: User learns to create context monitoring hook
|
|
- **WHEN** a user reads the context usage reporter example
|
|
- **THEN** they find a complete Python script that reads the transcript file
|
|
- **AND** they understand how to estimate token usage from conversation history
|
|
- **AND** they see the configuration for Stop hooks
|
|
- **AND** they understand the limitations of token estimation
|
|
|
|
#### Scenario: Hook output format is documented
|
|
- **WHEN** a user implements the context usage hook
|
|
- **THEN** they can generate a one-line report showing used tokens and remaining capacity
|
|
- **AND** the output shows realistic token counts based on conversation size
|
|
|
|
#### Scenario: Delta-based tracking is documented
|
|
- **WHEN** a user wants per-request token consumption
|
|
- **THEN** they find documentation pointing to the pre-message/post-response hook pair approach
|
|
- **AND** they understand how to use `UserPromptSubmit` + `Stop` for delta calculation
|