Skip to Content
Cheat Sheet/report-issue

/report-issue

File a structured bug report or feedback item from this downstream fork back to the upstream Gemba Flow repo — the channel that turns local pain points into upstream improvements.

When to use it

Run this when you’ve hit something the framework should fix (a hook that misbehaves, a skill spec that’s wrong, an agent template that’s broken) and you want the upstream maintainers to see it. The command drafts a structured issue body — title, environment, reproduction steps, expected vs actual behavior, a link back to this fork’s relevant artifacts — and files it on the upstream vibeacademy/gembaflow repo.

The intent is closing the feedback loop between downstream operators and the framework. Every fork has slightly different conditions; the upstream maintainers can’t see what’s breaking in your environment unless you tell them. The structured format ensures the report carries the information they need to reproduce and triage.

Use this for: framework defects (skills doing the wrong thing, hooks failing silently, agent templates with stale references), documentation gaps (a feature isn’t documented, or the docs are wrong), or feature requests (a workflow that the framework could support but doesn’t).

Don’t use this for project-specific issues (your fork’s bugs, your content’s typos) — those go on the fork’s own issue tracker via /create-ticket or the regular GitHub UI.

How it fits

The report lands upstream; if accepted and shipped, the next /upgrade on this fork pulls the fix in.

What it does (quick)

  • Asks targeted questions about what’s broken and what the expected behavior is
  • Reads your fork’s relevant artifacts (logs, config, the file that misbehaves) for the reproduction section
  • Drafts a structured issue body — title, environment, repro steps, expected vs actual, links back to this fork’s artifacts
  • Files the issue on the upstream vibeacademy/gembaflow repo
  • Outputs the upstream issue URL so you can track the response
  • /upgrade — the natural follow-up once the upstream fix ships
  • /doctor — often the source of a /report-issue invocation; surfaces framework-level problems worth filing upstream
  • /architect-review — when a framework limitation is architectural rather than a defect, this is the right tool first

Canonical spec: .claude/commands/report-issue.md

Last updated on
/validate-memory/eli5