give-feedback

# Give Feedback Send what you just learned about a cardano-dev-skills skill or bundled doc to the people who maintain it: a GitHub issue on `cardano-foundation/cardano-dev-skills`, under the user's own GitHub account, after one approval. Maintainers read every issue. The small gaps and the quiet wins are what make the skills better for the next agent. ## When to use - A bundled skill or doc was wrong, stale, misleading, or confusingly worded. - It lacked the one sentence, example, or warning that would have saved time. - A prompt should have matched a skill and didn't. - A skill or doc saved a real mistake or explained something unusually well. Praise is data: it tells maintainers what not to break. - The user asks: "send feedback", "report this skill", `/give-feedback`. Bias toward sending. A rough issue with a path and one sentence beats a perfect one never filed; weak signals are cheap to close, missing ones cannot be recovered. ## When NOT to use - General Cardano questions, or bugs in the user's own project. - Problems with an upstream project's software rather than with how it is documented here. Report those upstream. - Proposing a new documentation source. That form asks the human to attest the vetting bar; give them `https://github.com/cardano-foundation/cardano-dev-skills/issues/new?template=suggest-source.yml`. - Mid-task. Finish, then offer once at a natural pause. If the user declines, drop it for the rest of the session. ## Key principles 1. **Scrub before showing.** Remove mnemonics, signing keys, API keys and project ids, mainnet addresses, names, emails, home-directory paths, and private repo names. Replace them with `<redacted>`. 2. **Show the draft and ask once, in the same message.** After a yes, send. Do not re-confirm. If the user edits ("drop that line", "wrong skill"), apply and send. 3. **The user's identity, the user's words.** The issue goes out under their `gh` login. Quote what actually happened; never invent evidence. 4. **Send once.** One finding per issue; never retry after a success. ## Format Title: `[docs]`, `[topic]`, or `[feedback]` plus a short summary, with the label `documentation`, `enhancement`, or `feedback`. `[docs]` for anything wrong or stale, `[topic]` for something missing, `[feedback]` for praise, a prompt that missed, or general experience. One body shape for all three: ```markdown ### Where skills/<name>/SKILL.md (section "<heading>") or docs/sources/<source>/<file> ### What happened <what it said, what was expected, what actually happened; evidence if any> ### What would have helped <the missing sentence, example, or warning; or "keep doing this"> Agent: <Claude Code | Codex | Cursor | other> ``` ## Workflow ### Step 1: Gather From the conversation, not from a round of questions: the exact path (Glob or Grep under `${CLAUDE_SKILL_DIR}/../..` to confirm it — the repo root, so that both `skills/` and `docs/sources/` are reachable), what was asked, what the skill or doc said, what happened, and what would have helped. ### Step 2: Scrub Apply principle 1 to the title and the body. ### Step 3: Draft and ask once In one message: the title, the label, and the body in a fenced block, then "Ready to file this as a **public** issue on cardano-foundation/cardano-dev-skills, under your GitHub account. OK, or want to tweak it?" Say public every time. The repository is public, the draft is built from a working session that may not be, and visibility — not authorship — is what makes an accidental disclosure irreversible. ### Step 4: Send The body goes through stdin in a quoted heredoc, so it needs no shell quoting. The title is substituted into a double-quoted string, so it is one line of plain text with `` ` ``, `$`, `"` and `\` removed before substitution: ```bash gh issue create -R cardano-foundation/cardano-dev-skills \ --title "[docs] skills/<name>/SKILL.md: <short summary>" \ --label documentation \ --body-file - <<'ISSUE_BODY' ### Where ... ISSUE_BODY ``` If the host asks permission for the command, that prompt shows exactly what is being sent; proceed once it is approved, without re-asking in chat. If the command fails for any reason (no `gh`, not logged in, label rejected), say so in one line and give `https://github.com/cardano-foundation/cardano-dev-skills/issues/new/choose`; the draft above is what to paste. ### Step 5: Report One line: the issue URL, or "Not sent; draft and link above."