package-guide-learn

Package Guide Learn

Record newly discovered package pitfalls and patterns into the knowledge base. This skill enables the package-guide to grow autonomously from real debugging sessions.

Recording Procedure

Step 1: Extract Information

From the conversation context, extract:

• Package: Which package (soap, feel, dotween)
• Symptom: What the user observed (observable behavior)
• Root Cause: Technical explanation of why it happened
• Fix: What was changed to resolve it
• Prevention: Checklist items to avoid this in the future
• Source References: Relevant source files and line numbers

Step 2: Check for Duplicates

Read the existing pitfalls file:

${CLAUDE_PLUGIN_ROOT}/docs/{package}/pitfalls.md

Scan the troubleshooting table for matching symptoms. If a match exists:

• Update the existing entry if new information was found
• Do NOT create a duplicate

If the file does not exist, proceed to "Adding a New Package" section first.

Step 3: Create Detail File

Create a new file at:

${CLAUDE_PLUGIN_ROOT}/docs/{package}/pitfalls/{issue-name}.md

Use kebab-case for the filename derived from the core issue.

Follow this template:

# {Title}

## Symptom
{Observable behavior - what the user sees}

## Root Cause
{Technical explanation with code references}

## Fix
{Concrete solution - what to change}

## Prevention Checklist
- [ ] {Action item 1}
- [ ] {Action item 2}

## Related
- {Source file path}: {relevant code or setting}

Step 4: Update Pitfalls Index

Edit ${CLAUDE_PLUGIN_ROOT}/docs/{package}/pitfalls.md:

1. Add checklist item to the "Development Checklist" section
2. Add table row to the "Troubleshooting by Symptom" section:

   | {Symptom} | {Cause} | {Solution} | [Details](./pitfalls/{issue-name}.md) |
   

Step 5: Confirm

Report to the user what was recorded:

• Package name
• Issue title
• Files created/updated

Recording Patterns (Not Just Pitfalls)

If the debugging session revealed a useful pattern (not just a bug):

1. Read ${CLAUDE_PLUGIN_ROOT}/docs/{package}/patterns.md
2. Add the new pattern under the appropriate section
3. Include code example from the actual fix

Adding a New Package

If a pitfall is found for a package not yet tracked:

1. Create the directory structure:

   ${CLAUDE_PLUGIN_ROOT}/docs/{new-package}/
   ├── patterns.md
   ├── pitfalls.md
   └── pitfalls/
   

2. Initialize pitfalls.md with this structure:

   # {Package} Pitfalls
   
   ## Development Checklist
   
   Check before writing code:
   
   - [ ] {First checklist item from the discovery}
   
   ## Troubleshooting by Symptom
   
   | Symptom | Cause | Solution | Details |
   |---------|-------|----------|---------|
   

3. Initialize patterns.md with a package overview section
4. Update the lookup skill's Available Packages table in ${CLAUDE_PLUGIN_ROOT}/skills/lookup/SKILL.md:
   • Add new row with package name, description, and "Active" status
5. Record the first pitfall following the standard procedure above