me2resh/apexyard / .claude/skills/report-apexyard-bug
report-apexyard-bug
VerifiedReport a bug in the apexyard FRAMEWORK itself (hook misfire, skill gap, rule bug) — files a structured issue upstream to me2resh/apexyard. Distinct from /bug, which files into your own project.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
SKILL.md
View on GitHub---
name: report-apexyard-bug
description: Report a bug in the apexyard FRAMEWORK itself (hook misfire, skill gap, rule bug) — files a structured issue upstream to me2resh/apexyard. Distinct from /bug, which files into your own project.
argument-hint: "<short description of the framework bug>"
allowed-tools: Bash, Read, Write
---
# /report-apexyard-bug — Report a Framework Bug Upstream
Read `.claude/rules/writing-standard.md`. Use the **controlled technical writing profile** for the
upstream bug report: lead with the observed outcome and reproducible next action.
Files a structured GitHub Issue **about the apexyard framework itself** to the
canonical upstream **`me2resh/apexyard`** — for when a hook misfires, a skill is
broken, a rule produces a wrong result, or the docs are wrong.
This is the framework-feedback sibling of `/bug`. The difference is the target:
| Skill | Reports a bug in… | Files to… |
|-------|-------------------|-----------|
| `/bug` | your managed project's code | your project's own GitHub repo |
| **`/report-apexyard-bug`** | the apexyard **framework** (hooks / skills / rules / agents / docs) | **`me2resh/apexyard`** (upstream) |
> **Leak protection (mandatory).** This skill writes to a PUBLIC framework repo.
> NEVER include a registered private project's name, repo slug, or workspace path
> in the issue. Per `.claude/rules/leak-protection.md`, describe the context
> generically ("a registered project", "one of the managed workspaces"). The
> `block-private-refs-in-public-repos.sh` hook is the mechanical backstop, but
> scrub at authoring time — the private name is right there in your context while
> you write, and not referencing it takes active suppression.
## Usage
```
/report-apexyard-bug detect-role-trigger.sh fires on the wrong path
/report-apexyard-bug /handover crashes when the repo has no README
/report-apexyard-bug require-active-ticket blocks an exempt docs edit
```
## Process
### 0. Write the active-issue-skill marker (REQUIRED — me2resh/apexyard#268)
Before any `gh issue create`, write this skill's name to the active-issue-skill
marker so `require-skill-for-issue-create.sh` lets the command through. At entry:
```bash
# Ops root through the session pin (docs/skills/shared/ops-root.md).
ops_root=$(p="${APEXYARD_OPS_PIN_DIR:-$HOME/.claude/apexyard}/ops-root-${CLAUDE_CODE_SESSION_ID:-}"; r=""; [ -z "${APEXYARD_OPS_DISABLE_PIN:-}" ] && [ -f "$p" ] && IFS= read -r r < "$p"; [ -f "$r/.claude/hooks/_lib-ops-root.sh" ] || { r="$PWD"; while [ -n "$r" ] && [ ! -f "$r/.claude/hooks/_lib-ops-root.sh" ]; do r=${r%/*}; done; }; [ -f "$r/.claude/hooks/_lib-ops-root.sh" ] && . "$r/.claude/hooks/_lib-ops-root.sh" && resolve_ops_root) && [ -n "$ops_root" ] || { echo "No ops root. See docs/skills/shared/ops-root.md." >&2; exit 1; }
mkdir -p "$ops_root/.claude/session"
marker_home="$ops_root"
. "$marker_home/.claude/hooks/_lib-session-markers.sh"
skill_marker=$(active_issue_skill_marker_path "$marker_home") || { echo "A session id is required. Restart through the harness adapter." >&2; exit 2; }
echo "report-apexyard-bug" > "$skill_marker"
```
Remove the marker on **every** exit path (success, cancel, error):
```bash
marker_home="$ops_root"
. "$marker_home/.claude/hooks/_lib-session-markers.sh"
skill_marker=$(active_issue_skill_marker_path "$marker_home") || { echo "A session id is required. Restart through the harness adapter." >&2; exit 2; }
rm -f "$skill_marker"
```
### 1. Resolve the upstream repo
This skill always files **upstream**, regardless of the adopter's fork origin.
Resolve it (prefer the configured `upstream` remote; fall back to the canonical
slug):
```bash
UPSTREAM=$(git remote get-url upstream 2>/dev/null \
| sed -E 's#(git@github.com:|https://github.com/)##; s#\.git$##')
UPSTREAM="${UPSTREAM:-me2resh/apexyard}"
```
If `$UPSTREAM` doesn't look like `me2resh/apexyard` (a fork owner crept in via a
mis-set `upstream`), confirm with the user before filing, or default to the
canonical `me2resh/apexyard`.
### 2. Capture the framework version
So the maintainer knows which version the report is against, capture the version
from the fork (the SessionStart upstream-drift banner shows it; otherwise derive
it).
**Do NOT use `git describe --tags --abbrev=0`.** Under the release-cut branch
model, release tags (`vX.Y.Z`) are created on `main` and are NOT ancestors of
`dev`, so `git describe` from a `dev` checkout reports a stale version (observed:
`v1.1.0` when the line is actually `v2.2.0`) — every issue filed from `dev` would
be mislabeled (#503). Derive from `CHANGELOG.md` instead, which `/release-sync`
carries `main → dev`, so it is always current on `dev`:
```bash
# Primary: top-most `## [X.Y.Z]` heading in CHANGELOG.md (carried main→dev by
# /release-sync, so always the canonical current version on dev).
FW_VERSION=$(grep -m1 -oE '^## \[v?[0-9]+\.[0-9]+\.[0-9]+\]' "$ops_root/CHANGELOG.md" 2>/dev/null \
| grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
if [ -n "$FW_VERSION" ]; then
FW_VERSION="v$FW_VERSION" # keep the `v` prefix the field renders today
else
# Fallbacks: highest semver tag across ALL refs (catches main-only release
# tags via -v:refname sort) → short HEAD → literal "unknown".
FW_VERSION=$(git -C "$ops_root" tag --sort=-v:refname 2>/dev/null | head -1)
[ -z "$FW_VERSION" ] && FW_VERSION=$(git -C "$ops_root" rev-parse --short HEAD 2>/dev/null)
[ -z "$FW_VERSION" ] && FW_VERSION="unknown"
fi
```
### 3. Gather details (one question at a time)
Ask conversationally — do NOT batch. Wait for each answer.
**a) What part of the framework?** (which hook / skill / rule / agent / doc — e.g. `detect-role-trigger.sh`, `/handover`, `.claude/rules/leak-protection.md`)
**b) Given / When / Then** — what was the state, what did you do, what happened vs what should have happened.
**c) Repro** — the minimal steps. Include the exact command / skill invocation if relevant. **Scrub private project names** — use `<project>` / "a registered project".
**d) Severity** — `blocker` (can't work) / `major` (wrong result, workaround exists) / `minor` (cosmetic / docs).
**e) Anything else** — error output, the banner text, related issue numbers (optional).
### 4. Show the formatted issue for confirmation
Substitute into this body and display it for `yes / edit / cancel`. **Re-scan the
rendered body for any private project name before showing it.**
```
Here's the framework bug I'll file to <UPSTREAM>:
---
**[Bug] {title}**
## Affected
{hook / skill / rule / agent / doc}
## Given / When / Then
**Given** {state}
**When** {action}
**Then** {observed} — expected {expected}
## Repro
1. {step 1}
2. {step 2}
## Framework version
{FW_VERSION}
## Severity
{blocker | major | minor}
## Notes
{error output / banner / related issues, or "—"}
## Glossary
| Term | Definition |
|------|------------|
| {term} | {definition} |
---
Labels: bug
Repo: <UPSTREAM>
File this upstream? (yes / edit / cancel)
```
### 5. Handle response
- **yes** → create the issue
- **edit** / **change X** → update, re-show
- **cancel** / **no** → abort (and remove the marker)
### 6. Create the GitHub Issue
```bash
gh issue create --repo "$UPSTREAM" \
--title "[Bug] {title}" \
--label "bug" \
--body "{formatted body}"
```
If the `bug` label doesn't exist on the upstream repo, drop `--label` and note it
(don't fail the whole filing over a missing label — per the create-labels-first
convention, but upstream label management isn't the adopter's job).
### 7. Return the URL
```
Filed upstream: <UPSTREAM>#{number} — {title}
{url}
```
## Rules
1. **One question at a time.** Never batch. Wait for each answer.
2. **Always confirm before filing.** Show the full issue, get explicit "yes".
3. **Scrub private project names** — this writes to a PUBLIC repo. Describe context generically. See `.claude/rules/leak-protection.md`. Use the `<!-- private-refs: allow -->` body marker ONLY on explicit user confirmation that a name must stay.
4. **Always file upstream** — `me2resh/apexyard`, not the adopter's fork or a managed project.
5. **Capture the framework version** so the report is actionable.
6. **Label `bug`.** Title prefix `[Bug]`.
---
*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |