@vpxa/aikit 0.1.1

package/scaffold/general/skills/c4-architecture/references/common-mistakes.md

@@ -0,0 +1,437 @@
+# Common C4 Model Mistakes to Avoid
+
+This guide documents frequent anti-patterns and errors when creating C4 architecture diagrams, with examples of what to do instead.
+
+## Abstraction Level Mistakes
+
+### 1. Confusing Containers and Components
+
+**The Problem:**
+Containers are **deployable units** (applications, services, databases). Components are **non-deployable elements inside a container** (modules, classes, packages).
+
+**Wrong - Java class shown as container:**
+```mermaid
+C4Container
+  title WRONG: Class as Container
+
+  Container(userController, "UserController", "Java Class", "Handles user requests")
+  Container(userService, "UserService", "Java Class", "Business logic")
+  ContainerDb(db, "Database", "PostgreSQL", "User data")
+
+  Rel(userController, userService, "Calls")
+  Rel(userService, db, "Queries")
+```
+
+**Correct - Classes as components inside a container:**
+```mermaid
+C4Component
+  title CORRECT: Classes as Components
+
+  ContainerDb(db, "Database", "PostgreSQL", "User data")
+
+  Container_Boundary(api, "User API Service") {
+    Component(userController, "UserController", "Spring MVC", "REST endpoints")
+    Component(userService, "UserService", "Spring Bean", "Business logic")
+    Component(userRepo, "UserRepository", "JPA", "Data access")
+  }
+
+  Rel(userController, userService, "Calls")
+  Rel(userService, userRepo, "Uses")
+  Rel(userRepo, db, "Queries", "JDBC")
+```
+
+### 2. Adding Undefined Abstraction Levels
+
+**The Problem:**
+C4 defines exactly four levels. Don't invent "subcomponents", "modules", or other arbitrary levels.
+
+**Wrong:**
+- Level 3.5: "Subcomponents"
+- Level 2.5: "Microservice groups"
+- Custom levels like "packages" or "modules"
+
+**Correct:**
+Stick to Person, Software System, Container, Component. If you need more detail, you're at Level 4 (Code) which should use UML class diagrams.
+
+### 3. Vague Subsystems
+
+**The Problem:**
+"Subsystem" is ambiguous. Is it a system, container, or component?
+
+**Wrong:**
+```
+Subsystem(orders, "Order Subsystem", "Handles orders")
+```
+
+**Correct - Be specific:**
+```
+System(orderSystem, "Order System", "Handles order lifecycle")
+# OR
+Container(orderService, "Order Service", "Java", "Order processing API")
+# OR
+Component(orderProcessor, "Order Processor", "Spring Bean", "Order business logic")
+```
+
+## Shared Libraries Mistake
+
+**The Problem:**
+Modeling a shared library as a container implies it's an independently running service. Libraries are copied into applications, not deployed separately.
+
+**Wrong - Library as separate container:**
+```mermaid
+C4Container
+  title WRONG: Library as Container
+
+  Container(serviceA, "Service A", "Java")
+  Container(serviceB, "Service B", "Java")
+  Container(sharedLib, "Shared Utils Library", "Java", "Common utilities")
+
+  Rel(serviceA, sharedLib, "Uses")
+  Rel(serviceB, sharedLib, "Uses")
+```
+
+**Correct - Show library within each service:**
+```mermaid
+C4Component
+  title CORRECT: Library in Each Service
+
+  Container_Boundary(serviceA, "Service A") {
+    Component(controllerA, "Controller", "Spring MVC")
+    Component(utilsA, "Shared Utils", "Java Library", "Bundled copy")
+  }
+
+  Container_Boundary(serviceB, "Service B") {
+    Component(controllerB, "Controller", "Spring MVC")
+    Component(utilsB, "Shared Utils", "Java Library", "Bundled copy")
+  }
+```
+
+Or simply omit the library from architecture diagrams since it's an implementation detail.
+
+## Message Broker Mistakes
+
+### Single Message Bus Anti-Pattern
+
+**The Problem:**
+Showing Kafka/RabbitMQ as a single container creates a misleading "hub and spoke" diagram that hides actual data flows.
+
+**Wrong - Central message bus:**
+```mermaid
+C4Container
+  title WRONG: Central Message Bus
+
+  Container(orderSvc, "Order Service", "Java")
+  Container(inventorySvc, "Inventory Service", "Java")
+  Container(paymentSvc, "Payment Service", "Java")
+  ContainerQueue(kafka, "Kafka", "Event Streaming", "Message bus")
+
+  Rel(orderSvc, kafka, "Publishes/Subscribes")
+  Rel(inventorySvc, kafka, "Publishes/Subscribes")
+  Rel(paymentSvc, kafka, "Publishes/Subscribes")
+```
+
+**Correct - Individual topics:**
+```mermaid
+C4Container
+  title CORRECT: Individual Topics
+
+  Container(orderSvc, "Order Service", "Java", "Creates orders")
+  Container(inventorySvc, "Inventory Service", "Java", "Manages stock")
+  Container(paymentSvc, "Payment Service", "Java", "Processes payments")
+
+  ContainerQueue(orderCreated, "order.created", "Kafka", "New orders")
+  ContainerQueue(stockReserved, "stock.reserved", "Kafka", "Stock events")
+  ContainerQueue(paymentComplete, "payment.complete", "Kafka", "Payment events")
+
+  Rel(orderSvc, orderCreated, "Publishes")
+  Rel(inventorySvc, orderCreated, "Consumes")
+  Rel(inventorySvc, stockReserved, "Publishes")
+  Rel(paymentSvc, stockReserved, "Consumes")
+  Rel(paymentSvc, paymentComplete, "Publishes")
+  Rel(orderSvc, paymentComplete, "Consumes")
+```
+
+**Alternative - Topics on relationship labels:**
+```mermaid
+C4Container
+  title ALTERNATIVE: Topics as Labels
+
+  Container(orderSvc, "Order Service", "Java")
+  Container(inventorySvc, "Inventory Service", "Java")
+  Container(paymentSvc, "Payment Service", "Java")
+
+  Rel(orderSvc, inventorySvc, "order.created", "Kafka")
+  Rel(inventorySvc, paymentSvc, "stock.reserved", "Kafka")
+  Rel(paymentSvc, orderSvc, "payment.complete", "Kafka")
+```
+
+## External Systems Mistakes
+
+### Showing Internal Details of External Systems
+
+**The Problem:**
+You don't control external systems. Showing their internals creates coupling and becomes stale quickly.
+
+**Wrong - External system internals:**
+```mermaid
+C4Container
+  title WRONG: External System Internals
+
+  Container(myApp, "My App", "Node.js")
+
+  System_Boundary(stripe, "Stripe") {
+    Container(stripeApi, "Stripe API", "Ruby")
+    Container(stripeWorker, "Payment Worker", "Java")
+    ContainerDb(stripeDb, "Payment DB", "MySQL")
+  }
+
+  Rel(myApp, stripeApi, "Charges cards")
+```
+
+**Correct - External system as black box:**
+```mermaid
+C4Context
+  title CORRECT: External System Black Box
+
+  Container(myApp, "My App", "Node.js", "E-commerce backend")
+  System_Ext(stripe, "Stripe", "Payment processing platform")
+
+  Rel(myApp, stripe, "Processes payments", "REST API")
+```
+
+## Metadata and Documentation Mistakes
+
+### 1. Removing Type Labels
+
+**The Problem:**
+Removing element type labels (Container, Component, System) to "simplify" diagrams creates ambiguity.
+
+**Wrong:**
+```
+Box(api, "API")  # What is this? System? Container? Component?
+```
+
+**Correct:**
+```
+Container(api, "API Application", "Spring Boot", "REST API backend")
+```
+
+### 2. Missing Descriptions
+
+**The Problem:**
+Elements without descriptions force viewers to guess their purpose.
+
+**Wrong:**
+```
+Container(svc, "Service", "Java")
+```
+
+**Correct:**
+```
+Container(orderSvc, "Order Service", "Spring Boot", "Manages order lifecycle and fulfillment")
+```
+
+### 3. Generic Relationship Labels
+
+**The Problem:**
+Labels like "uses" or "communicates with" don't explain what data flows or why.
+
+**Wrong:**
+```
+Rel(frontend, api, "Uses")
+Rel(api, db, "Accesses")
+```
+
+**Correct:**
+```
+Rel(frontend, api, "Fetches products, submits orders", "JSON/HTTPS")
+Rel(api, db, "Reads/writes order data", "JDBC")
+```
+
+## Diagram Scope Mistakes
+
+### 1. Not Tailoring to Audience
+
+**The Problem:**
+Showing Level 4 code diagrams to executives, or only Level 1 to developers who need implementation details.
+
+| Audience | Appropriate Levels |
+|----------|-------------------|
+| Executives | Level 1 (Context) only |
+| Product Managers | Levels 1-2 |
+| Architects | Levels 1-3 |
+| Developers | All levels as needed |
+| DevOps | Levels 2 + Deployment |
+
+### 2. Creating All Four Levels by Default
+
+**The Problem:**
+Not every system needs all four levels. Level 3 (Component) and Level 4 (Code) often add no value.
+
+**Guidance:**
+- **Always create:** Context (L1) and Container (L2)
+- **Create if valuable:** Component (L3) for complex containers
+- **Rarely create:** Code (L4) - let IDEs generate these
+
+### 3. Too Many Elements Per Diagram
+
+**The Problem:**
+Diagrams with 20+ elements become unreadable.
+
+**Simon Brown's advice:** "If a diagram with a dozen boxes is hard to understand, don't draw a diagram with a dozen boxes!"
+
+**Solutions:**
+- Split by bounded context or domain
+- Create separate diagrams per service
+- Show one service + its direct dependencies
+- Use multiple focused diagrams instead of one comprehensive diagram
+
+## Arrow Mistakes
+
+### 1. Bidirectional Arrows
+
+**The Problem:**
+Bidirectional arrows are ambiguous. Who initiates the call? What flows each direction?
+
+**Wrong:**
+```
+BiRel(frontend, api, "Data")  # Ambiguous direction
+```
+
+**Correct:**
+```
+Rel(frontend, api, "Requests products", "JSON/HTTPS")
+Rel(api, frontend, "Returns product data", "JSON/HTTPS")
+```
+
+Or show the initiator's perspective:
+```
+Rel(frontend, api, "Fetches products", "JSON/HTTPS")
+```
+
+### 2. Unlabeled Arrows
+
+**The Problem:**
+Arrows without labels force readers to guess what flows between elements.
+
+**Wrong:**
+```
+Rel(orderSvc, paymentSvc)
+```
+
+**Correct:**
+```
+Rel(orderSvc, paymentSvc, "Requests payment authorization", "gRPC")
+```
+
+## Deployment Diagram Mistakes
+
+### 1. Deployment Details in Container Diagrams
+
+**The Problem:**
+Container diagrams should show logical architecture, not infrastructure details.
+
+**Wrong - Infrastructure in container diagram:**
+```mermaid
+C4Container
+  title WRONG: Infrastructure in Container Diagram
+
+  Container(api1, "API (Instance 1)", "Java", "Primary")
+  Container(api2, "API (Instance 2)", "Java", "Replica")
+  Container(api3, "API (Instance 3)", "Java", "Replica")
+  Container(lb, "Load Balancer", "HAProxy", "Distributes traffic")
+  ContainerDb(primary, "Primary DB", "PostgreSQL", "Write")
+  ContainerDb(replica, "Read Replica", "PostgreSQL", "Read")
+```
+
+**Correct - Use Deployment diagram for infrastructure:**
+```mermaid
+C4Deployment
+  title CORRECT: Deployment Diagram for Infrastructure
+
+  Deployment_Node(lb, "Load Balancer", "AWS ALB") {
+    Container(alb, "ALB", "AWS", "Traffic distribution")
+  }
+
+  Deployment_Node(ecs, "ECS Cluster", "Fargate") {
+    Container(api1, "API Instance 1", "Spring Boot")
+    Container(api2, "API Instance 2", "Spring Boot")
+    Container(api3, "API Instance 3", "Spring Boot")
+  }
+
+  Deployment_Node(rds, "RDS", "Multi-AZ") {
+    ContainerDb(primary, "Primary", "PostgreSQL")
+    ContainerDb(replica, "Replica", "PostgreSQL")
+  }
+```
+
+### 2. Missing Environment Context
+
+**The Problem:**
+Deployment diagrams should specify which environment (production, staging, dev).
+
+**Wrong:**
+```
+C4Deployment
+  title Deployment Diagram  # Which environment?
+```
+
+**Correct:**
+```
+C4Deployment
+  title Deployment Diagram - Production (AWS us-east-1)
+```
+
+## Consistency Mistakes
+
+### 1. Inconsistent Notation Across Diagrams
+
+**The Problem:**
+Using different colors, shapes, or terminology for the same elements across diagrams.
+
+**Wrong:**
+- Context diagram: "Payment System" (blue)
+- Container diagram: "Payment Service" (green)
+- Component diagram: "Payment Module" (red)
+
+**Correct:**
+Use consistent naming, colors, and styling. Create a style guide for your team.
+
+### 2. No Legend/Key
+
+**The Problem:**
+Assuming viewers understand your notation without explanation.
+
+**Solution:**
+Always include a legend explaining colors, shapes, and line styles. Even for "obvious" elements.
+
+## Decision Documentation Mistakes
+
+### Showing Decision Process in Diagrams
+
+**The Problem:**
+Architecture diagrams show **outcomes** of decisions, not the decision-making process.
+
+**Wrong approach:**
+Including "Option A vs Option B" annotations in diagrams.
+
+**Correct approach:**
+- Document decisions separately in Architecture Decision Records (ADRs)
+- Link ADRs to relevant diagrams
+- Diagrams show the chosen architecture, ADRs explain why
+
+## Quick Reference: Checklist
+
+Before finalizing any C4 diagram, verify:
+
+- [ ] Every element has: name, type, technology (if applicable), description
+- [ ] All arrows are unidirectional with action verb labels
+- [ ] Technology/protocol included on relationships
+- [ ] Diagram has a clear, specific title
+- [ ] Under 20 elements (ideally under 15)
+- [ ] Appropriate level for the target audience
+- [ ] Containers are deployable, components are not
+- [ ] External systems shown as black boxes
+- [ ] Message topics shown individually (not as single broker)
+- [ ] No infrastructure details in container diagrams
+- [ ] Consistent with other diagrams in the set

package/scaffold/general/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/scaffold/general/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.