zhongwei/gh-nathanonn-claude-skill-build-insights-logger-claude-skills-build-insights-logger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:41:49 +08:00
commit 40079aabc6
4 changed files with 380 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,11 @@
{
"name": "build-insights-logger",
"description": "Automatically log meaningful insights, discoveries, and decisions during coding sessions. Capture non-trivial learnings about edge cases, design decisions, patterns, and implementation details. Activate when building complex code where institutional knowledge should be preserved. Log to .claude/insights/ and help transfer key learnings to CLAUDE.md.",
"version": "1.0.0",
"author": {
"name": "Nathan Onn"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# build-insights-logger
Automatically log meaningful insights, discoveries, and decisions during coding sessions. Capture non-trivial learnings about edge cases, design decisions, patterns, and implementation details. Activate when building complex code where institutional knowledge should be preserved. Log to .claude/insights/ and help transfer key learnings to CLAUDE.md.

321
SKILL.md Normal file
View File

@@ -0,0 +1,321 @@
---
name: build-insights-logger
description: Automatically log meaningful insights, discoveries, and decisions during coding sessions. Capture non-trivial learnings about edge cases, design decisions, patterns, and implementation details. Activate when building complex code where institutional knowledge should be preserved. Log to .claude/insights/ and help transfer key learnings to CLAUDE.md.
---
# Build Insights Logger
## Overview
Maintain a running log of meaningful insights, discoveries, and decisions made during coding sessions. Capture non-trivial learnings about requirements, edge cases, design considerations, implementation details, and coding patterns that emerge during development.
**Target outcome**: Preserve institutional knowledge and track the evolution of the codebase by logging insights to session files in `.claude/insights/`, then selectively transferring valuable learnings to CLAUDE.md.
## When to Use This Skill
Activate automatically when:
- Working on complex implementations with non-trivial design decisions
- Discovering edge cases or unexpected behaviors
- Making architectural or performance trade-offs
- Implementing security-sensitive features
- Building features where institutional knowledge matters
Do not activate for:
- Simple bug fixes or trivial changes
- Routine refactoring without architectural impact
- Syntax corrections or typos
## File Structure & Session Management
### Directory Structure
```
.claude/
└── insights/
├── session-YYYY-MM-DD-HHMMSS.md (current session)
└── archive/
└── session-YYYY-MM-DD-HHMMSS.md (archived sessions)
```
### Session File Naming
- **Current session**: `session-YYYY-MM-DD-HHMMSS.md`
- **Format**: Use timestamp in `YYYY-MM-DD-HHMMSS` format
- **Location**: `.claude/insights/` for active sessions
- **Archive location**: `.claude/insights/archive/` for completed sessions
### Session Creation
- Create new session file when first insight is logged in a new Claude Code session
- One file per Claude Code session
- Each session file is independent - no cross-session merging
### Session File Format
Each session file contains insights in markdown format with this structure:
```markdown
# Insights Session: YYYY-MM-DD HH:MM:SS
### [Category]: [Brief Title]
Files: `path/to/file.ts`, `another/file.ts`
Tags: #tag1 #tag2 #tag3
YYYY-MM-DD HH:MM:SS
[Clear, concise description of the insight]
[Optional: Brief code snippet if essential - max 3-5 lines]
---
### [Next insight...]
```
## Logging Insights Workflow
### When to Log Insights
**Automatic logging triggers** (Claude decides these are insight-worthy):
- Discovery of non-trivial edge cases
- New requirements emerging during implementation
- Design decisions and their rationale
- Performance considerations or optimizations
- Security implications discovered
- Dependency choices and trade-offs
- Architectural patterns adopted
- Testing strategies implemented
- Error handling approaches
- API design decisions
- State management patterns
- Data validation rules
**Explicit user requests**:
- User says "log this insight", "remember this", or "capture this learning"
- User asks to note specific discoveries
- User highlights something for future reference
### What NOT to Log
- Trivial or obvious details (e.g., "created a new file")
- Standard boilerplate code
- Common language features
- Syntax corrections or typos
- Routine refactoring without architectural impact
- Self-evident code comments
### Logging Process
**Step 1: Identify the insight**
- Evaluate whether the discovery/decision meets insight criteria
- When in doubt, log it (user can filter during review)
**Step 2: Create or open session file**
- If no session file exists for current session, create `.claude/insights/session-YYYY-MM-DD-HHMMSS.md`
- If session file exists, open it for appending
**Step 3: Format the insight**
Use this template:
```markdown
### [Category]: [Brief Title]
Files: `path/to/file.ts`, `another/file.ts`
Tags: #tag1 #tag2 #tag3
YYYY-MM-DD HH:MM:SS
[Clear, concise description of the insight]
[Optional: Brief code snippet if essential - max 3-5 lines]
```
**Category examples**:
- Architecture, Edge Cases, Performance, Testing, Security
- Dependencies, Patterns, API Design, State Management
- Error Handling, Data Flow, Validation
**Tag guidelines**:
- Use lowercase with hyphens: `#error-handling`, `#api-design`
- 2-4 tags per insight
- Common tags: `#performance`, `#security`, `#edge-cases`, `#patterns`, `#testing`, `#api`, `#architecture`
**Description guidelines**:
- **Clear and concise**: Get to the point quickly
- **Explain WHY**: Why is this valuable? What problem does it solve?
- **Context**: What led to this discovery?
- **Action taken**: What decision was made?
- **1-3 paragraphs maximum**
**Code snippet rules** (optional):
- Only include if essential to understanding
- Maximum 3-5 lines
- Add comments to highlight key points
- Label "good" vs "bad" when comparing approaches
- Prefer conceptual explanation over code
**Step 4: Append to session file**
- Add insight to the end of the session file
- Separate insights with `---` divider
**Step 5: Notify user**
- Show brief notification: `📝 Logged insight about [topic]`
- Keep it one line - don't show full insight content
- Example: `📝 Logged insight about null handling in API responses`
### Logging Frequency
- Add insights progressively as discovered
- Don't wait until end of session
- Multiple insights per session is expected and encouraged
## Review & Selection Workflow
### Initiating Review
- **User-initiated only**: User asks "review insights", "show me what we learned", "summarize insights"
- **No automatic suggestions**: Do not proactively suggest reviewing
### Review Process
**Step 1: Consolidation**
- Read current session insights file from `.claude/insights/session-*.md`
- Identify related or redundant insights
- Consolidate similar insights into cohesive entries
- Refine wording for clarity
**Step 2: Present insights**
Present in this format:
```
Based on this session, here are the key insights captured:
**[Category Group]**
1/ Insight: [Brief title]
Files: [file paths]
Explanation: [Why this matters and what was learned]
2/ Insight: [Brief title]
Files: [file paths]
Explanation: [Why this matters and what was learned]
**[Another Category Group]**
3/ Insight: [Brief title]
Files: [file paths]
Explanation: [Why this matters and what was learned]
Which insights would you like to add to CLAUDE.md? Reply with numbers (e.g., "1, 3" or "all").
```
**Presentation guidelines**:
- Number each insight (1/, 2/, 3/, etc.)
- Group by category when helpful
- Include brief explanation of value for each
- Keep explanations concise (1-2 sentences)
**Step 3: User selection**
- User responds with numbers: "1, 3" or "1,2,3" or "all" or "none"
- Parse user's selection
**Step 4: Add to CLAUDE.md**
- Read existing CLAUDE.md (or create if doesn't exist)
- Add selected insights under appropriate section
- Format appropriately for CLAUDE.md context
- Create new section if needed (e.g., "## Insights & Learnings")
- Confirm what was added to user
**Step 5: Archive session file**
- After adding insights to CLAUDE.md, move session file to archive
- Move from `.claude/insights/session-*.md` to `.claude/insights/archive/session-*.md`
- Create archive directory if it doesn't exist
- Confirm archiving to user
### No Insights Scenario
If user asks to review and no insights were logged:
- Respond: "No insights were captured in this session yet."
- Don't create empty session files
### Multiple Review Requests
- User can request review multiple times per session
- Show all insights logged so far
- If some were previously added to CLAUDE.md, indicate which ones
### CLAUDE.md Doesn't Exist
- If CLAUDE.md doesn't exist, create it when adding insights
- Use standard structure with appropriate sections
- Add insights under "## Insights & Learnings" section
## Archiving & Cleanup
### Automatic Archiving
- **Trigger**: After user selects insights and they're added to CLAUDE.md
- **Action**: Move session file from `.claude/insights/` to `.claude/insights/archive/`
- **Naming**: Keep original filename (e.g., `session-2025-11-17-143022.md`)
- **Directory creation**: Create `.claude/insights/archive/` if it doesn't exist
### Manual Deletion Option
User can request deletion instead of archiving:
- **Trigger phrases**: "delete the insights log", "clear insights instead of archiving", "remove insights file"
- **Confirmation**: Ask for confirmation before deleting
- **Action**: Delete the session file completely instead of archiving
### Cleanup Commands
- "archive current session" - move to archive
- "delete current session" - delete completely (with confirmation)
- "clean up old archives" - user specifies which archived files to remove
## Quality Guidelines
### Insight Quality Criteria
1. **Non-trivial**: Adds genuine value to understanding the codebase
2. **Actionable**: Contains information useful for future development
3. **Specific**: Tied to concrete decisions or discoveries, not generic advice
4. **Contextual**: Explains why this matters for this specific project
### When in Doubt
- **Better to log**: If uncertain whether something is insight-worthy, log it
- **User can filter**: During review, user decides what's valuable for CLAUDE.md
- **Better too many than too few**: Session log is temporary; missing insights are lost
### Writing Style
- **Concise**: Shorter entries are better
- **Clear**: Use plain language, avoid jargon unless necessary
- **Focused**: One insight per entry, don't combine unrelated learnings
- **Practical**: Focus on practical implications, not theoretical concepts
### Category Selection
- Choose specific, descriptive categories
- Create new categories when existing ones don't fit
- Avoid generic categories like "General" or "Miscellaneous"
- Categories should help organize related insights
### Tag Selection
- Use 2-4 tags per insight
- Tags should aid searchability and filtering
- Use consistent tag names (check existing tags in file first)
- Prefer specific tags over broad ones
## Edge Cases & Special Scenarios
### Session File Already Exists
- If timestamp collision (unlikely), append a letter: `session-2025-11-17-143022-a.md`
- Log warning about timestamp collision
### Archive Directory Doesn't Exist
- Create `.claude/insights/archive/` directory when first archiving
- Don't error if it doesn't exist
### Empty Session
- Don't create session file until first insight is logged
- If no insights logged, no file created
### Long Sessions with Many Insights
- No limit on insights per session
- File can grow as large as needed
- Consolidate during review to prevent overwhelming user
## Example Insight Entry
```markdown
### Edge Case: Null handling in API responses
Files: `api/users.ts`, `types/user.ts`
Tags: #api #edge-cases #error-handling
2025-11-17 14:30:22
Discovered that third-party user API can return null for email field even though documentation states it's required. Added validation layer with fallback to 'no-email@placeholder.com' for system processes to prevent downstream crashes.
// Good approach
const email = userData.email ?? 'no-email@placeholder.com';
// Avoid - will crash downstream
const email = userData.email; // assumes always present
```

45
plugin.lock.json Normal file
View File

@@ -0,0 +1,45 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:nathanonn/claude-skill-build-insights-logger:.claude/skills/build-insights-logger",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "9c475bb3ea96df728de4d7fd9d516a4c667ff2f3",
"treeHash": "d6ee22a47add431ffd35f51f806f13b99438f1f68e8f5e6aee6dc4b1ae6407b7",
"generatedAt": "2025-11-28T10:27:13.882257Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "build-insights-logger",
"description": "Automatically log meaningful insights, discoveries, and decisions during coding sessions. Capture non-trivial learnings about edge cases, design decisions, patterns, and implementation details. Activate when building complex code where institutional knowledge should be preserved. Log to .claude/insights/ and help transfer key learnings to CLAUDE.md.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "000c049f3f0e5572c57c38de3842bd42f7d7985f03bcc281dc6869f00c309aba"
},
{
"path": "SKILL.md",
"sha256": "3543f493f6d3ea35bf691ee5f6f99e647c744fbde40d4b193a32ce3b58685fcd"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "20eb1d0f5ca06cd73ba970b0de1040d1faaeded90e9e682734425edb5d70af41"
}
],
"dirSha256": "d6ee22a47add431ffd35f51f806f13b99438f1f68e8f5e6aee6dc4b1ae6407b7"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}