Help us improve
Share bugs, ideas, or general feedback.
From popkit-core
Captures structured bug reports from Claude Code sessions with context like recent tools, errors, git status, and stuck patterns. Invoke on /popkit:bug or repeated agent failures.
npx claudepluginhub jrc1883/popkit-ai --plugin popkit-coreHow this skill is triggered — by the user, by Claude, or both
Slash command
/popkit-core:pop-bug-reporterThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Capture and report bugs with automatic context gathering, local logging, GitHub issue creation, and pattern sharing.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Breaks plans, specs, or PRDs into thin vertical-slice issues on the project issue tracker using tracer bullets. Useful for converting high-level work into grabbable implementation tickets.
Share bugs, ideas, or general feedback.
Capture and report bugs with automatic context gathering, local logging, GitHub issue creation, and pattern sharing.
/popkit:bugSECURITY.md disclosure, not the public bug log.User provides:
--issue, --share, --verbose, --no-contextlist, view <id>, clearDetermine the action:
list: List logged bugsview: View specific bugclear: Clear logsGather automatic context using hooks/utils/bug_context.py:
from bug_context import BugContextCapture, format_bug_report, format_github_issue
capture = BugContextCapture()
ctx = capture.capture(
description=user_description,
recent_tools=recent_tool_calls,
agent_state=current_agent_state
)
Context includes:
Bug reports follow a fixed schema. Every named slot is required unless labeled Optional:. No free-form fields.
Schema:
Bug Report
==========
ID: bug-<YYYY-MM-DD>-<slug>
Time: <ISO-8601>
Description: <one-sentence user statement; no hedging>
Context:
Language: <detected>
Framework: <detected | none>
Branch: <git branch>
Uncommitted: <N files>
Recent Actions:
<n>. <tool>: <target> (<status>)
Repeat for up to 10 most recent tool calls
Errors Detected:
[<ErrorType>] <message>
Repeat once per distinct error, or write "none"
Stuck Patterns:
- <pattern>: <evidence>
Repeat once per detected pattern, or write "none"
Suggested Actions:
- <imperative verb> <object>
Provide 1-3 actions, imperative mood only
Optional: Reproduction Steps
1. <step>
2. <step>
Example (filled):
Bug Report
==========
ID: bug-2024-12-04-abc123
Time: 2024-12-04T10:30:00Z
Description: Agent got stuck on OAuth flow
Context:
Language: TypeScript
Framework: Next.js
Branch: feature/oauth
Uncommitted: 3 files
Recent Actions:
1. Edit: src/auth/oauth.ts (ok)
2. Bash: npm run build (failed)
3. Edit: src/auth/oauth.ts (ok, 2nd edit to same file)
Errors Detected:
[TypeError] Cannot read property 'token' of undefined
Stuck Patterns:
- Same file edited 3 times: oauth.ts
- Build command failed twice
Suggested Actions:
- Revert the last two edits to oauth.ts and re-read the module.
- Check the refresh-token path for null before property access.
Suggested-action rules:
Revert, Check, Add, Remove). No consider, try, may, should.Based on flags:
Default - Log locally:
file_path = capture.save(ctx)
print(f"Logged to: {file_path}")
--issue - Create GitHub issue with validated labels (Issue #96):
from popkit_shared.utils.github_validator import validate_labels
from popkit_shared.utils.github_cache import GitHubCache
issue_body = format_github_issue(ctx)
# Validate default bug labels
default_labels = ["bug", "needs-triage"]
cache = GitHubCache()
valid, invalid, suggestions = validate_labels(default_labels, cache)
# Auto-fix or fallback
if invalid:
fixed_labels = valid.copy()
for s in suggestions:
if s['suggestions']:
fixed_labels.append(s['suggestions'][0])
labels_to_use = fixed_labels if fixed_labels else []
else:
labels_to_use = valid
# Create issue (don't block on invalid labels)
if labels_to_use:
gh issue create --title "Bug: ..." --body issue_body --label {','.join(labels_to_use)}
else:
gh issue create --title "Bug: ..." --body issue_body
--share - Share to collective (Pro/Team):
# Anonymize pattern
# Upload to collective learning database
Show:
bugs = capture.list_bugs(limit=10)
# Format as table with ID, date, description
ctx = capture.get_bug(bug_id)
if ctx:
print(format_bug_report(ctx, verbose=True))
cleared = capture.clear_bugs(before=date, bug_id=id)
print(f"Cleared {cleared} bug reports")
When --share is used, anonymize before uploading:
| Original | Anonymized |
|---|---|
<project>/src/auth/oauth.ts | auth module |
handleTokenRefresh() | token refresh handler |
| API keys, secrets | [REDACTED] |
| Variable names | Generic terms |
def anonymize_pattern(ctx: BugContext) -> Dict:
return {
"trigger": abstract_error(ctx.errors[0] if ctx.errors else None),
"context": {
"language": ctx.project.language,
"framework": ctx.project.framework,
"error_type": ctx.errors[0].error_type if ctx.errors else None
},
"stuck_patterns": ctx.stuck_patterns,
"suggested_actions": ctx.suggested_actions
}
User: /popkit:bug "Agent can't find the right file"
[Capturing context...]
- Recent tools: 8 calls
- Files touched: 4
- Errors: 1 (ENOENT)
- Git: feature/search branch
Bug Report
==========
ID: bug-2024-12-04-def456
...
Logged to: .claude/bugs/bug-2024-12-04-def456.json
User: /popkit:bug "Tests failing after refactor" --issue
[Capturing context...]
[Creating GitHub issue...]
Bug Report Created
==================
ID: bug-2024-12-04-ghi789
GitHub Issue: #123
URL: https://github.com/user/repo/issues/123
Logged locally and issue created.
User: /popkit:bug "OAuth token refresh failing" --share
[Capturing context...]
[Anonymizing pattern...]
[Uploading to collective...]
Bug Report
==========
ID: bug-2024-12-04-jkl012
Pattern shared: Yes (anonymized)
Collective ID: pattern-abc123
Thank you for contributing to the collective learning database!
| Component | Purpose |
|---|---|
hooks/utils/bug_context.py | Context capture and formatting |
.claude/bugs/ | Local bug storage |
power-mode/insight_embedder.py | Pattern sharing |
gh issue create | GitHub issue creation |
Use a clear, structured format: