Skip to content

Commit 8b7fc49

Browse files
committed
docs(procedures): formalize See Also pattern for knowledge linking
Add see-also-pattern.md procedure to standardize bidirectional linking between related concepts. This formalizes the pattern introduced with the Jonah-throughput links. Principle: systems-stewardship
1 parent 6ec6623 commit 8b7fc49

2 files changed

Lines changed: 55 additions & 0 deletions

File tree

knowledge/procedures/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Actionable processes and workflows that evolve with experience.
55
- `fs-write-full-paths.md` - Always use absolute paths in fs_write operations
66
- `git-workflow.md` - Git conventions and branch management
77
- `post-pr-mini-retro.md` - Systems improvement retro after feature PRs
8+
- `see-also-pattern.md` - Bidirectional linking between related concepts
89
- `worktree-workflow.md` - Git worktree workflow (beta/imperfect system)
910

1011
## Future Procedure Ideas
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# See Also Pattern
2+
3+
A standardized approach for creating bidirectional links between related concepts in our knowledge base, similar to Notion's backlinks or Wikipedia's "See also" sections.
4+
5+
## When to Use
6+
7+
Add a "See Also" section when:
8+
- Two concepts are philosophically related (e.g., Jonah personality ↔ throughput definition)
9+
- One concept implements or embodies another (e.g., a procedure that implements a principle)
10+
- Understanding one concept enhances understanding of another
11+
- There's a source material relationship (e.g., concepts derived from the same book)
12+
13+
## Format
14+
15+
Always place the "See Also" section at the end of the document, after all main content:
16+
17+
```markdown
18+
## See Also
19+
- [Link Text](relative/path/to/file.md) - Brief description of why this is related
20+
- External Resource Name - Context for external references
21+
```
22+
23+
## Guidelines
24+
25+
1. **Make it bidirectional**: If A links to B, then B should link back to A
26+
2. **Use relative paths**: Enable navigation regardless of where the repo is cloned
27+
3. **Add context**: Include a brief description of the relationship
28+
4. **Keep it focused**: Only link truly related concepts, not everything tangentially connected
29+
5. **Update both files**: When adding a link, always update both ends of the relationship
30+
31+
## Examples
32+
33+
**In a principle file:**
34+
```markdown
35+
## See Also
36+
- [Git Workflow](../procedures/git-workflow.md) - Procedure that implements this principle
37+
- [Jonah Personality](../../.claude/personalities/jonah.md) - Consultant persona that teaches this concept
38+
```
39+
40+
**In a personality file:**
41+
```markdown
42+
## See Also
43+
- [Throughput Definition](../../knowledge/throughput-definition.md) - The North Star principle this persona helps discover
44+
- The Goal by Eliyahu M. Goldratt - Source material for this persona
45+
```
46+
47+
## Benefits
48+
49+
- Creates a knowledge graph for navigating related concepts
50+
- Reduces duplication by linking rather than repeating
51+
- Helps discover connections between ideas
52+
- Enables both human browsing and potential future tooling
53+
54+
This pattern supports the [Systems Stewardship](../principles/systems-stewardship.md) principle by creating consistent, maintainable knowledge structures.

0 commit comments

Comments
 (0)