atxtechbro / atxtechbro/dotfiles

[Procedures] Optimize knowledge/ procedures for token efficiency

Open
#1,098 1 comment 0 reactions 0 assignees View on GitHub
ai developer-experience documentation enhancement mcp systems-stewardship
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.