@vpxa/kb 0.1.13 → 0.1.16

package/skills/lesson-learned/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: lesson-learned
+description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
+---
+
+# Lesson Learned
+
+Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
+
+## Before You Begin
+
+**Load the principles reference first.**
+
+1. Read `references/se-principles.md` to have the principle catalog available
+2. Optionally read `references/anti-patterns.md` if you suspect the changes include areas for improvement
+3. Determine the scope of analysis (see Phase 1)
+
+**Do not proceed until you've loaded at least `se-principles.md`.**
+
+## Phase 1: Determine Scope
+
+Ask the user or infer from context what to analyze.
+
+| Scope | Git Commands | When to Use |
+|-------|-------------|-------------|
+| Feature branch | `git log main..HEAD --oneline` + `git diff main...HEAD` | User is on a non-main branch (default) |
+| Last N commits | `git log --oneline -N` + `git diff HEAD~N..HEAD` | User specifies a range, or on main (default N=5) |
+| Specific commit | `git show <sha>` | User references a specific commit |
+| Working changes | `git diff` + `git diff --cached` | User says "what about these changes?" before committing |
+
+**Default behavior:**
+- If on a feature branch: analyze branch commits vs main
+- If on main: analyze the last 5 commits
+- If the user provides a different scope, use that
+
+## Phase 2: Gather Changes
+
+1. Run `git log` with the determined scope to get the commit list and messages
+2. Run `git diff` for the full diff of the scope
+3. If the diff is large (>500 lines), use `git diff --stat` first, then selectively read the top 3-5 most-changed files
+4. **Read commit messages carefully** -- they contain intent that raw diffs miss
+5. Only read changed files. Do not read the entire repo.
+
+## Phase 3: Analyze
+
+Identify the **dominant pattern** -- the single most instructive thing about these changes.
+
+Look for:
+- **Structural decisions** -- How was the code organized? Why those boundaries?
+- **Trade-offs made** -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)
+- **Problems solved** -- What was the before/after? What made the "after" better?
+- **Missed opportunities** -- Where could the code improve? (present gently as "next time, consider...")
+
+Map findings to specific principles from `references/se-principles.md`. Be specific -- quote actual code, reference actual file names and line changes.
+
+## Phase 4: Present the Lesson
+
+Use this template:
+
+```markdown
+## Lesson: [Principle Name]
+
+**What happened in the code:**
+[2-3 sentences describing the specific change, referencing files and commits]
+
+**The principle at work:**
+[1-2 sentences explaining the SE principle]
+
+**Why it matters:**
+[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]
+
+**Takeaway for next time:**
+[One concrete, actionable sentence the user can apply to future work]
+```
+
+If there is a second lesson worth noting (maximum 2 additional):
+
+```markdown
+---
+
+### Also worth noting: [Principle Name]
+
+**In the code:** [1 sentence]
+**The principle:** [1 sentence]
+**Takeaway:** [1 sentence]
+```
+
+## What NOT to Do
+
+| Avoid | Why | Instead |
+|-------|-----|---------|
+| Listing every principle that vaguely applies | Overwhelming and generic | Pick the 1-2 most relevant |
+| Analyzing files that were not changed | Scope creep | Stick to the diff |
+| Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |
+| Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |
+| Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |
+| More than 3 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
+
+## Conversation Style
+
+- **Reflective, not prescriptive.** Use the user's own code as primary evidence.
+- **Never say "you should have..."** -- instead use "the approach here shows..." or "next time you face this, consider..."
+- **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
+- **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
+- **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.

package/skills/lesson-learned/references/anti-patterns.md

@@ -0,0 +1,55 @@
+---
+description: Common anti-patterns to detect in code diffs. Use alongside se-principles.md for balanced analysis -- principles show what's good, anti-patterns show what to watch for.
+---
+
+# Anti-Patterns
+
+When analyzing a diff, check for these signals. Present findings gently -- as opportunities, not failures.
+
+## God Object / God Class
+
+One module doing too much.
+**Diff signals:** A single file with many unrelated changes. One class/module imported everywhere. A file over 500 lines that keeps growing.
+**Suggest:** Extract responsibilities into focused modules (SRP).
+
+## Shotgun Surgery
+
+One logical change scattered across many files.
+**Diff signals:** 10+ files changed for a single feature or fix. The same type of edit repeated in many places. A rename or config change touching dozens of files.
+**Suggest:** Consolidate the scattered logic. If one change requires editing many files, the abstraction boundaries may be wrong.
+
+## Feature Envy
+
+A function that uses another module's data more than its own.
+**Diff signals:** Heavy cross-module imports. A function reaching deep into another object's properties. Utility functions that only serve one caller in a different module.
+**Suggest:** Move the function closer to the data it uses.
+
+## Premature Abstraction
+
+Abstracting before there are multiple concrete cases.
+**Diff signals:** An interface with exactly one implementation. A factory that creates only one type. A generic solution for a problem that exists only once.
+**Suggest:** Wait for the second or third use case before abstracting (Rule of Three).
+
+## Copy-Paste Programming
+
+Duplicated code blocks with minor variations.
+**Diff signals:** Similar code appearing in multiple places in the diff. Functions that differ by only a parameter or two. Repeated patterns that could be parameterized.
+**Suggest:** Extract shared logic, parameterize the differences.
+
+## Magic Numbers / Strings
+
+Literal values without explanation.
+**Diff signals:** Hardcoded numbers in conditions (`if (retries > 3)`). String literals used as keys or identifiers. Timeouts, limits, or thresholds without named constants.
+**Suggest:** Extract to named constants that explain the "why."
+
+## Long Method
+
+Functions that do too much.
+**Diff signals:** New functions over 40-50 lines. Functions with multiple levels of nesting. Functions that require scrolling to read.
+**Suggest:** Extract sub-steps into named functions. Each function should do one thing.
+
+## Excessive Comments
+
+Comments explaining "what" instead of "why."
+**Diff signals:** Comments restating the code (`// increment counter`). Large comment blocks before straightforward code. Commented-out code left in place.
+**Suggest:** Make the code self-documenting through better naming. Use comments only for "why" -- intent, trade-offs, non-obvious constraints.

package/skills/lesson-learned/references/se-principles.md

@@ -0,0 +1,109 @@
+---
+description: Curated catalog of software engineering principles. Load this before analyzing code changes so you can map observations to named principles.
+---
+
+# Software Engineering Principles
+
+Use this as a lookup table. When you spot a pattern in a diff, find the matching principle here. Each entry includes **code signals** -- what to look for in actual changes.
+
+## Design Principles (SOLID)
+
+**Single Responsibility Principle (SRP)**
+A module should have one reason to change.
+Code signals: A class/file was split into two. A function was extracted. A component stopped handling both UI and data fetching.
+
+**Open/Closed Principle (OCP)**
+Open for extension, closed for modification.
+Code signals: New behavior added without changing existing code. A plugin/hook/callback system introduced. Strategy pattern or configuration used instead of conditionals.
+
+**Liskov Substitution Principle (LSP)**
+Subtypes must be substitutable for their base types.
+Code signals: An interface was introduced to unify implementations. A subclass override changed behavior in a way that broke callers (violation). Type narrowing or guards added.
+
+**Interface Segregation Principle (ISP)**
+No client should depend on methods it doesn't use.
+Code signals: A large interface was split into smaller ones. Optional methods removed from an interface. A "fat" props object was broken into focused ones.
+
+**Dependency Inversion Principle (DIP)**
+Depend on abstractions, not concretions.
+Code signals: A concrete dependency replaced with an interface/injection. A factory or provider pattern introduced. Import paths changed from specific implementations to abstract layers.
+
+**Composition over Inheritance**
+Favor object composition over class inheritance.
+Code signals: Inheritance hierarchy replaced with delegation. Mixins or HOCs replaced with hooks or composition. A "base class" was removed.
+
+## Simplicity Principles
+
+**DRY (Don't Repeat Yourself)**
+Every piece of knowledge should have a single representation.
+Code signals: Duplicate code extracted into a shared function. A constant replaced repeated literals. A template/generator replaced copy-pasted boilerplate.
+
+**KISS (Keep It Simple, Stupid)**
+The simplest solution that works is the best.
+Code signals: A complex abstraction replaced with a straightforward implementation. Unnecessary indirection removed. A clever one-liner replaced with readable code.
+
+**YAGNI (You Aren't Gonna Need It)**
+Don't build it until you actually need it.
+Code signals: Speculative features removed. Unused configuration options deleted. An over-engineered solution simplified to match actual requirements.
+
+**Rule of Three**
+Wait until the third duplication before abstracting.
+Code signals: Similar code exists in 2 places and was left alone (good). A premature abstraction was introduced after only one use (violation). Third occurrence triggered extraction (textbook application).
+
+**Principle of Least Surprise**
+Code should behave the way most users would expect.
+Code signals: A function renamed to better describe what it does. Return types made consistent. Side effects made explicit or removed.
+
+## Structural Principles
+
+**Separation of Concerns**
+Different responsibilities should live in different modules.
+Code signals: Business logic extracted from UI components. Data access separated from domain logic. Configuration separated from behavior. A "god file" split into focused modules.
+
+**High Cohesion**
+Related functionality should live together.
+Code signals: Scattered related functions gathered into one module. A utility file broken up so each piece lives near its consumers. A feature folder created.
+
+**Loose Coupling**
+Modules should depend on each other as little as possible.
+Code signals: Direct imports replaced with events/callbacks. A shared dependency removed. Modules communicate through well-defined interfaces instead of reaching into internals.
+
+**Encapsulation**
+Hide internal details, expose only what's necessary.
+Code signals: Public methods reduced. Internal helpers made private. A module's API surface shrunk. Implementation details hidden behind a facade.
+
+**Information Hiding**
+Modules should not expose their internal data structures.
+Code signals: Raw data structures wrapped in accessor methods. Internal state made private. A data transformation moved inside the module that owns the data.
+
+## Pragmatic Principles
+
+**Boy Scout Rule**
+Leave the code better than you found it.
+Code signals: Small cleanups alongside a feature change. A renamed variable for clarity. A dead code path removed. An outdated comment updated.
+
+**Fail Fast**
+Detect and report errors as early as possible.
+Code signals: Input validation added at entry points. Assertions added for invariants. Early returns replacing deep nesting. Error handling moved closer to the source.
+
+**Defensive Programming**
+Anticipate and handle unexpected inputs gracefully.
+Code signals: Null checks added. Default values provided. Edge cases handled. Error boundaries introduced.
+
+**Premature Optimization (avoiding it)**
+Don't optimize until you've measured.
+Code signals: A simple implementation chosen over a "faster" complex one. Readability prioritized over micro-performance. A profiling step added before optimization work.
+
+## Refactoring Patterns
+
+**Extract Method/Function**
+Code signals: A long function split into named sub-functions. Inline logic replaced with a well-named call.
+
+**Extract Class/Module**
+Code signals: A file split into multiple files. A class split into two with distinct responsibilities.
+
+**Replace Conditional with Polymorphism**
+Code signals: A switch/if-else chain replaced with a strategy pattern or subclass dispatch. A type map introduced.
+
+**Introduce Parameter Object**
+Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.

package/skills/requirements-clarity/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: requirements-clarity
+description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
+---
+
+# Requirements Clarity Skill
+
+## Description
+
+Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.
+
+
+## Instructions
+
+When invoked, detect vague requirements:
+
+1. **Vague Feature Requests**
+   - User says: "add login feature", "implement payment", "create dashboard"
+   - Missing: How, with what technology, what constraints?
+
+2. **Missing Technical Context**
+   - No technology stack mentioned
+   - No integration points identified
+   - No performance/security constraints
+
+3. **Incomplete Specifications**
+   - No acceptance criteria
+   - No success metrics
+   - No edge cases considered
+   - No error handling mentioned
+
+4. **Ambiguous Scope**
+   - Unclear boundaries ("user management" - what exactly?)
+   - No distinction between MVP and future enhancements
+   - Missing "what's NOT included"
+
+**Do NOT activate when**:
+- Specific file paths mentioned (e.g., "auth.go:45")
+- Code snippets included
+- Existing functions/classes referenced
+- Bug fixes with clear reproduction steps
+
+## Core Principles
+
+1. **Systematic Questioning**
+   - Ask focused, specific questions
+   - One category at a time (2-3 questions per round)
+   - Build on previous answers
+   - Avoid overwhelming users
+
+2. **Quality-Driven Iteration**
+   - Continuously assess clarity score (0-100)
+   - Identify gaps systematically
+   - Iterate until ≥ 90 points
+   - Document all clarification rounds
+
+3. **Actionable Output**
+   - Generate concrete specifications
+   - Include measurable acceptance criteria
+   - Provide executable phases
+   - Enable direct implementation
+
+## Clarification Process
+
+### Step 1: Initial Requirement Analysis
+
+**Input**: User's requirement description
+
+**Tasks**:
+1. Parse and understand core requirement
+2. Generate feature name (kebab-case format)
+3. Determine document version (default `1.0` unless user specifies otherwise)
+4. Ensure `./docs/prds/` exists for PRD output
+5. Perform initial clarity assessment (0-100)
+
+**Assessment Rubric**:
+```
+Functional Clarity: /30 points
+- Clear inputs/outputs: 10 pts
+- User interaction defined: 10 pts
+- Success criteria stated: 10 pts
+
+Technical Specificity: /25 points
+- Technology stack mentioned: 8 pts
+- Integration points identified: 8 pts
+- Constraints specified: 9 pts
+
+Implementation Completeness: /25 points
+- Edge cases considered: 8 pts
+- Error handling mentioned: 9 pts
+- Data validation specified: 8 pts
+
+Business Context: /20 points
+- Problem statement clear: 7 pts
+- Target users identified: 7 pts
+- Success metrics defined: 6 pts
+```
+
+**Initial Response Format**:
+```markdown
+I understand your requirement. Let me help you refine this specification.
+
+**Current Clarity Score**: X/100
+
+**Clear Aspects**:
+- [List what's clear]
+
+**Needs Clarification**:
+- [List gaps]
+
+Let me systematically clarify these points...
+```
+
+### Step 2: Gap Analysis
+
+Identify missing information across four dimensions:
+
+**1. Functional Scope**
+- What is the core functionality?
+- What are the boundaries?
+- What is out of scope?
+- What are edge cases?
+
+**2. User Interaction**
+- How do users interact?
+- What are the inputs?
+- What are the outputs?
+- What are success/failure scenarios?
+
+**3. Technical Constraints**
+- Performance requirements?
+- Compatibility requirements?
+- Security considerations?
+- Scalability needs?
+
+**4. Business Value**
+- What problem does this solve?
+- Who are the target users?
+- What are success metrics?
+- What is the priority?
+
+### Step 3: Interactive Clarification
+
+**Question Strategy**:
+1. Start with highest-impact gaps
+2. Ask 2-3 questions per round
+3. Build context progressively
+4. Use user's language
+5. Provide examples when helpful
+
+**Question Format**:
+```markdown
+I need to clarify the following points to complete the requirements document:
+
+1. **[Category]**: [Specific question]?
+   - For example: [Example if helpful]
+
+2. **[Category]**: [Specific question]?
+
+3. **[Category]**: [Specific question]?
+
+Please provide your answers, and I'll continue refining the PRD.
+```
+
+**After Each User Response**:
+1. Update clarity score
+2. Capture new information in the working PRD outline
+3. Identify remaining gaps
+4. If score < 90: Continue with next round of questions
+5. If score ≥ 90: Proceed to PRD generation
+
+**Score Update Format**:
+```markdown
+Thank you for the additional information!
+
+**Clarity Score Update**: X/100 → Y/100
+
+**New Clarified Content**:
+- [Summarize new information]
+
+**Remaining Points to Clarify**:
+- [List remaining gaps if score < 90]
+
+[If score < 90: Continue with next round of questions]
+[If score ≥ 90: "Perfect! I will now generate the complete PRD document..."]
+```
+
+### Step 4: PRD Generation
+
+Once clarity score ≥ 90, generate comprehensive PRD.
+
+**Output File**:
+
+1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`
+
+Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
+
+## PRD Document Structure
+
+```markdown
+# {Feature Name} - Product Requirements Document (PRD)
+
+## Requirements Description
+
+### Background
+- **Business Problem**: [Describe the business problem to solve]
+- **Target Users**: [Target user groups]
+- **Value Proposition**: [Value this feature brings]
+
+### Feature Overview
+- **Core Features**: [List of main features]
+- **Feature Boundaries**: [What is and isn't included]
+- **User Scenarios**: [Typical usage scenarios]
+
+### Detailed Requirements
+- **Input/Output**: [Specific input/output specifications]
+- **User Interaction**: [User operation flow]
+- **Data Requirements**: [Data structures and validation rules]
+- **Edge Cases**: [Edge case handling]
+
+## Design Decisions
+
+### Technical Approach
+- **Architecture Choice**: [Technical architecture decisions and rationale]
+- **Key Components**: [List of main technical components]
+- **Data Storage**: [Data models and storage solutions]
+- **Interface Design**: [API/interface specifications]
+
+### Constraints
+- **Performance Requirements**: [Response time, throughput, etc.]
+- **Compatibility**: [System compatibility requirements]
+- **Security**: [Security considerations]
+- **Scalability**: [Future expansion considerations]
+
+### Risk Assessment
+- **Technical Risks**: [Potential technical risks and mitigation plans]
+- **Dependency Risks**: [External dependencies and alternatives]
+- **Schedule Risks**: [Timeline risks and response strategies]
+
+## Acceptance Criteria
+
+### Functional Acceptance
+- [ ] Feature 1: [Specific acceptance conditions]
+- [ ] Feature 2: [Specific acceptance conditions]
+- [ ] Feature 3: [Specific acceptance conditions]
+
+### Quality Standards
+- [ ] Code Quality: [Code standards and review requirements]
+- [ ] Test Coverage: [Testing requirements and coverage]
+- [ ] Performance Metrics: [Performance test pass criteria]
+- [ ] Security Review: [Security review requirements]
+
+### User Acceptance
+- [ ] User Experience: [UX acceptance criteria]
+- [ ] Documentation: [Documentation delivery requirements]
+- [ ] Training Materials: [If needed, training material requirements]
+
+## Execution Phases
+
+### Phase 1: Preparation
+**Goal**: Environment preparation and technical validation
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 2: Core Development
+**Goal**: Implement core functionality
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 3: Integration & Testing
+**Goal**: Integration and quality assurance
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 4: Deployment
+**Goal**: Release and monitoring
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+---
+
+**Document Version**: 1.0
+**Created**: {timestamp}
+**Clarification Rounds**: {clarification_rounds}
+**Quality Score**: {quality_score}/100
+```
+
+## Behavioral Guidelines
+
+### DO
+- Ask specific, targeted questions
+- Build on previous answers
+- Provide examples to guide users
+- Maintain conversational tone
+- Summarize clarification rounds within the PRD
+- Use clear, professional English
+- Generate concrete specifications
+- Stay in clarification mode until score ≥ 90
+
+### DON'T
+- Ask all questions at once
+- Make assumptions without confirmation
+- Generate PRD before 90+ score
+- Skip any required sections
+- Use vague or abstract language
+- Proceed without user responses
+- Exit skill mode prematurely
+
+## Success Criteria
+
+- Clarity score ≥ 90/100
+- All PRD sections complete with substance
+- Acceptance criteria checklistable (using `- [ ]` format)
+- Execution phases actionable with concrete tasks
+- User approves final PRD
+- Ready for development handoff