atxtechbro / atxtechbro/dotfiles
[Procedures] Optimize knowledge/ procedures for token efficiency
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
# Optimize Knowledge Directory for Token Efficiency
## Problem
All content in `knowledge/` is preloaded into every Claude Code session via `--add-dir` flag. This means detailed procedures cost tokens and add cognitive noise even when not needed.
## Current Impact
Files like `knowledge/procedures/mcp-error-reporting.md` contain detailed steps, examples, and explanations that:
- Cost tokens in every session
- Distract from core work
- Are only needed on a need-to-know basis
## Proposed Solution
### 1. Keep procedures concise in knowledge/
- Essential philosophy/principle (1-2 lines)
- When to use (1 line)
- Link to detailed documentation
### 2. Move details elsewhere
- Detailed steps → `.github/ISSUE_TEMPLATE/` or `docs/`
- Examples → External docs
- Long explanations → Reference material outside knowledge/
### 3. Structure Example
```markdown
# MCP Error Reporting
Report errors with our custom MCP tools (git/github) to create self-healing systems.
**When to use**: When mcp__git__ or mcp__github__ tools fail
**Action**: Create issue using [MCP Tool Error template](/.github/ISSUE_TEMPLATE/mcp-tool-error.md)
Details: See full procedure in docs/procedures/mcp-error-reporting-full.md
```
## Files to Review
- [ ] mcp-error-reporting.md
- [ ] close-issue-procedure.md
- [ ] worktree-workflow.md
- [ ] git-workflow.md
- [ ] issue-to-pr-workflow.md
- [ ] procedure-creation.md
## Benefits
- Reduced token usage per session
- Better focus on current task
- Details available when needed
- Follows subtraction-creates-value principle
## Related Principles
- subtraction-creates-value
- selective-optimization (80/20 rule)
Contributor guide
No contributing guide indexed for this repository
Research direction
Review the six listed files in knowledge/procedures, then compare the proposed destinations in .github/ISSUE_TEMPLATE/ and docs/. Identify which detailed steps, examples, and explanations can move while preserving a concise principle, usage note, and link in each procedure. Done means the selected procedures are shorter, their details remain available in the named destinations, and the links resolve.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100