From laravel-api-tool-kit
Scans conversation for confirmed findings (bugs, patterns, decisions, gotchas) and appends them to project knowledge files in rules/, workflows/, or feature-specific docs.
How this command is triggered — by the user, by Claude, or both
Slash command
/laravel-api-tool-kit:update-knowledgelaravel-api-tool-kit/workflows/The summary Claude sees in its command listing — used to decide when to auto-load this command
# Workflow: Update Knowledge Base Run this after completing a feature, fixing a bug, discovering a non-obvious data pattern, or making an architectural decision. Preserves learnings so future sessions start where this one ended. **Trigger phrases**: "update knowledge", "update the skill", "remember this", "save what we learned", "update skills" **Also trigger proactively** — if a significant discovery was confirmed during the session (root cause found, non-obvious gotcha, reusable pattern), run this without being asked. --- ## Step 1 — Scan the Conversation Review the full conversatio...
Run this after completing a feature, fixing a bug, discovering a non-obvious data pattern, or making an architectural decision. Preserves learnings so future sessions start where this one ended.
Trigger phrases: "update knowledge", "update the skill", "remember this", "save what we learned", "update skills"
Also trigger proactively — if a significant discovery was confirmed during the session (root cause found, non-obvious gotcha, reusable pattern), run this without being asked.
Review the full conversation. Extract findings in these categories:
| Category | Examples |
|---|---|
| Root cause confirmed | "The bug was X because Y — verified with data/tests" |
| Pattern confirmed | "We consistently do X for Y in this project" |
| Anti-pattern found | "Never do X — it causes Y (confirmed with evidence)" |
| Decision made | "We chose X over Y because Z" |
| New constraint | "Field X must always be Y", "This API requires Z format" |
| Investigation insight | "When symptom X appears, always check Y first" |
| DB / data gotcha | "Column X is VARCHAR not INT", "Use scope X not Y for this query type" |
| Fix / solution | "The fix was to use X instead of Y" |
Skip:
ORDER_ID, USER_ID placeholders)There are two types of knowledge to update. Choose the right one:
These go into the skill's rules/ and workflows/ files.
| Finding type | Target |
|---|---|
| General coding rule | Closest rule file (rules/code-quality.md, rules/models.md, etc.) |
| Anti-pattern with wrong/correct example | rules/anti-patterns.md |
| Component-specific pattern | That component's rule file (rules/actions.md, rules/filters.md, etc.) |
| Multi-step process | Existing workflow or new workflows/[name].md |
| Project-level default | SKILL.md → Project Defaults section |
These go into per-feature knowledge docs in knowledge/[FEATURE].md. Use this for:
Knowledge location depends on the AI tool: .claude/knowledge/ (Claude Code), .agent/knowledge/ (Antigravity), or knowledge/ at project root (Cursor/Copilot). One file per feature area — never one file per investigation ticket.
Knowledge file template:
# [Feature Name] Knowledge
Last Updated: YYYY-MM-DD
## How It Works
Brief description of the feature's core flow.
## Issues Found & Fixed
### Issue 1: [Short title]
**Symptom**: What the user reported.
**Root cause**: What actually caused it (with data evidence).
**Fix**: What was changed.
**Diagnostic query** (if applicable):
\`\`\`sql
SELECT ... FROM ... WHERE feature_id = FEATURE_ID;
\`\`\`
## Key Lessons
- When [symptom X] → always check [Y] first
- [Column/field] is [type] not [assumed type]
## DB Gotchas
- `table.column` is VARCHAR not INT — use `'value'` not `12`
Rules for writing:
ORDER_ID, Car, User — never session-specific namesGood (directive format):
**NEVER access a relationship in a Resource without `whenLoaded()`**
// Wrong — causes N+1 on every request
'brand' => $this->brand->name,
// Correct
'brand' => $this->whenLoaded('brand')?->name,
Bad (narrative format):
We found that in the CarResource, accessing the brand relationship directly
was causing N+1 queries because we didn't use whenLoaded(). This happened
during the cars refactor in March 2026 when we added the brand relationship.
# [Rule / Component Name]
## Rules
- MUST ...
- NEVER ...
## [Pattern Name]
\`\`\`php
// Wrong
...
// Correct
...
\`\`\`
Tell the user exactly what changed:
Updated rules/models.md:
→ Added: ULID models must declare $keyType = 'string' and $incrementing = false
Updated rules/anti-patterns.md:
→ Added: NEVER access relationship in Resource without whenLoaded() (N+1)
Created knowledge/orders.md:
→ Documented root cause: order status is VARCHAR not INT — always quote it
→ Added diagnostic query: check stuck orders by status + created_at range
Nothing new for rules/controllers.md — already covered.
If nothing new: "All learnings from this session are already covered in the knowledge base."
❌ Writing narrative ("In this session we discovered...")
❌ Including specific IDs — use placeholders (ORDER_ID, USER_ID)
❌ Adding unconfirmed findings — only what was verified
❌ Creating a new rule file for a single one-off finding — add to an existing file
❌ Creating a new knowledge doc per investigation ticket — one file per feature
❌ Skipping the read-before-write check (duplicates)
✅ Write directives: "When X → do Y" ✅ Include reusable code/SQL with generic placeholders ✅ Separate architectural rules (rules/) from project knowledge (knowledge/) ✅ Keep findings brief and scannable ✅ Always read the target file before writing to it
npx claudepluginhub ahmedesa/laravel-api-tool-kit/learnExtracts patterns, quirks, and decisions from the current conversation and persists them to the project's knowledge base in knowledge/learnings/.
/learnExtracts reusable knowledge patterns from the current conversation session, evaluates quality via 5 dimensions, and updates CLAUDE.md, rules/, memory-bank/. Supports --status, --export, --import file, --eval flags.
/learn-evalExtracts reusable patterns from the session, self-evaluates quality via checklist and verdict, determines Global or Project save location, and saves approved skills.
/save-session-learningsGathers session learnings from git history and conversation, categorizes into architecture/patterns/gotchas/commands/decisions, checks for duplicates, and appends to CLAUDE.md and AGENTS.md.