Skip to content

Commit 676a401

Browse files
committed
refactor(procedures): audit and restructure for clarity
Major restructuring to document actual workflow vs aspirational procedures: Added: - issue-to-pr-workflow.md: Documents the actual mechanical flow from GitHub issue to merged PR - coding-conventions.md: Consolidates micro-procedures (fs paths, uv usage) Updated: - README.md: Restructured to highlight core workflow first, organize by importance Removed experimental/unused procedures: - ears-requirements.md: Never integrated into actual workflow - see-also-pattern.md: Aspirational, not used - non-interactive-execution.md: Not referenced - fs-write-full-paths.md: Consolidated into coding-conventions.md - uv-usage.md: Consolidated into coding-conventions.md This creates an honest representation of our actual workflow: GitHub Issue → Planning Mode → Implementation → PR → Review Principle: systems-stewardship Principle: subtraction-creates-value
1 parent 94e26b5 commit 676a401

8 files changed

Lines changed: 157 additions & 137 deletions

knowledge/procedures/README.md

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,37 @@
22

33
Actionable processes and workflows that evolve with experience.
44

5-
- `configuration-as-data.md` - Prefer declarative JSON over imperative scripts
6-
- `fs-write-full-paths.md` - Always use absolute paths in fs_write operations
7-
- `git-workflow.md` - Git conventions and branch management
5+
## 🎯 Core Workflow
6+
7+
**Start here**: Our work follows a mechanical flow from issue to value delivery.
8+
9+
### [Issue-to-PR Workflow](issue-to-pr-workflow.md)
10+
The complete flow: `GitHub Issue → Planning Mode → Implementation → Pull Request → Review → Merge`
11+
12+
This is THE workflow. Everything else supports this core process.
13+
14+
## Supporting Workflows
15+
16+
### Active Development
17+
- `tmux-git-worktrees-claude-code.md` - The 100x productivity system with planning mode
18+
- `git-workflow.md` - Git conventions and branch management
19+
- `worktree-workflow.md` - Git worktree isolation for parallel development
20+
- `slash-command-generation.md` - How slash commands like `/close-issue` work
21+
22+
### Quality & Improvement
823
- `post-pr-mini-retro.md` - Systems improvement retro after feature PRs
9-
- `see-also-pattern.md` - Bidirectional linking between related concepts
10-
- `worktree-workflow.md` - Git worktree workflow (beta/imperfect system)
24+
- `five-focusing-steps.md` - Identify and optimize constraints
25+
26+
### Conventions & Standards
27+
- `coding-conventions.md` - File paths, Python tools, and other learned patterns
28+
- `configuration-as-code.md` - Prefer declarative JSON over imperative scripts
29+
30+
### Tool Integration
31+
- `mcp-client-integration.md` - Adding new MCP clients to the ecosystem
32+
- `mcp-tool-logging.md` - MCP server tool-level logging
33+
- `mcp-protocol-smoke-test.md` - Testing MCP protocol directly
34+
- `mcp-prompts.md` - Adding prompts to MCP servers
1135

12-
## Future Procedure Ideas
13-
- **Self-organizing README**: Automate README.md reorganization based on git log activity patterns (daily GitHub Action analyzing last 1000 commits)
36+
### Tips & Setup
37+
- `agent-permission-setup.md` - Configure tool permissions for agents
38+
- `claude-code-tips.md` - Tips and shortcuts for Claude Code
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Coding Conventions
2+
3+
Small but important conventions learned through experience. These prevent common errors and ensure consistency.
4+
5+
## File Operations
6+
7+
### Always Use Absolute Paths
8+
**Rule**: Use `/full/path` or `~/path` - never relative paths like `./file`
9+
10+
This prevents path resolution errors, especially with tools like fs_write.
11+
12+
**Validation from Anthropic**: "We found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory. To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly." ([Source](https://www.anthropic.com/engineering/building-effective-agents))
13+
14+
## Python Development
15+
16+
### Use UV for Package Management
17+
Use `uv` instead of `pip` for all Python packaging operations:
18+
- `uv pip install package` instead of `pip install package`
19+
- Modern, fast, and consistent with current best practices
20+
21+
## Configuration
22+
23+
### Prefer Data Over Code
24+
When configuring tools, prefer declarative JSON/YAML over imperative scripts. See [configuration-as-code](configuration-as-code.md) for detailed patterns.
25+
26+
## Git Operations
27+
28+
### Use MCP Git Tools
29+
Always use `mcp__git__*` tools instead of bash git commands:
30+
- Better error handling
31+
- Consistent interface
32+
- Proper path resolution
33+
34+
## These Are Living Conventions
35+
36+
This list grows as we learn. When you discover a pattern that prevents errors or improves consistency, add it here with a brief explanation of why it matters.

knowledge/procedures/ears-requirements.md

Lines changed: 0 additions & 39 deletions
This file was deleted.

knowledge/procedures/fs-write-full-paths.md

Lines changed: 0 additions & 13 deletions
This file was deleted.
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Issue-to-PR Workflow
2+
3+
The mechanical workflow that delivers value: from GitHub issue to merged pull request.
4+
5+
## The Complete Flow
6+
7+
```
8+
GitHub Issue → Planning Mode → Implementation → Pull Request → Review → Merge
9+
```
10+
11+
## Step-by-Step Mechanics
12+
13+
### 1. GitHub Issue Defines the Work
14+
15+
Every task starts as a GitHub issue:
16+
- Clear problem statement
17+
- Success criteria defined
18+
- Labels indicate type (bug, feature, spike)
19+
20+
**Anti-pattern**: Starting work without an issue leads to scope creep and unclear PRs.
21+
22+
### 2. Planning Mode Review
23+
24+
Run `/close-issue <number>` with planning mode (default):
25+
- Claude analyzes the issue
26+
- Presents a plan for review
27+
- You approve, refine, or reject
28+
29+
**Key insight**: This shifts you from "driving" to "managing" - you review plans, not implementation details.
30+
31+
### 3. Implementation in Isolation
32+
33+
Once plan is approved:
34+
- Automatic worktree creation for complete isolation
35+
- Claude implements in focused sessions
36+
- Each commit represents verified progress
37+
38+
**Tools involved**:
39+
- [Git worktrees](worktree-workflow.md) for isolation
40+
- [Git workflow](git-workflow.md) for commits
41+
- MCP tools for file operations
42+
43+
### 4. Pull Request Packages the Solution
44+
45+
Implementation complete:
46+
- Push branch to remote
47+
- Create PR referencing "Closes #<issue>"
48+
- PR description explains the solution
49+
50+
**Quality gates**:
51+
- Small, focused changes (planning mode enables this)
52+
- Clear connection to original issue
53+
- Tests pass, linting clean
54+
55+
### 5. Review Completes the Cycle
56+
57+
PR review happens at the right altitude:
58+
- Review the solution, not individual lines
59+
- Verify it solves the original issue
60+
- Merge when approved
61+
62+
### 6. Optional: Post-PR Retro
63+
64+
For significant work:
65+
- Run [post-PR mini retro](post-pr-mini-retro.md)
66+
- Capture learnings
67+
- Update procedures if needed
68+
69+
## Why This Works
70+
71+
1. **Clear boundaries**: Issues define WHAT, PRs deliver solutions
72+
2. **Parallel execution**: Multiple issues → multiple agents → multiple PRs
73+
3. **Quality through planning**: Better plans = better PRs
74+
4. **Reduced cognitive load**: Review plans and PRs, not live coding
75+
76+
## Configuration
77+
78+
Enable planning mode by default:
79+
```bash
80+
# In ~/.claude/settings.json
81+
{
82+
"defaultMode": "plan"
83+
}
84+
```
85+
86+
## Related
87+
88+
- [tmux + git worktrees + Claude Code + Planning Mode](tmux-git-worktrees-claude-code.md) - The complete productivity system
89+
- [OSE Principle](../principles/ose.md) - Why this workflow embodies management over doing

knowledge/procedures/non-interactive-execution.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

knowledge/procedures/see-also-pattern.md

Lines changed: 0 additions & 66 deletions
This file was deleted.

knowledge/procedures/uv-usage.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)