docs: add raise-issue skill for writing newcomer-readable issues

[susheem-k]

What

Adds .claude/skills/raise-issue/SKILL.md — a structure for writing issues in this repo — and links it from the "Open an issue first" step in CONTRIBUTING.md.

Why

Issues here assume vocabulary the repo never explains anywhere: run vs request, ledger, governor, PriceFn, Micros, why Halt extends BaseException. Without that, a reader cannot tell a bug from the design — several behaviours that look broken are deliberate invariants, and an issue that does not say so gets relitigated in review instead of fixed.

The skill asks for four sections:

Section	Answers	Failure if skipped
Context	What is this part of TokenOps, and how does it work?	Reader cannot tell whether the behaviour is a bug or the design
Problem	What is wrong, shown in code and observed output?	Reader debates whether the problem is real
Proposed approach	What should change, concretely?	Issue becomes a complaint, not work
Tradeoffs / non-scope	What was rejected, and what this is not?	Settled choices get relitigated; scope creeps

It also carries the terms worth defining, a rule to read every file:line before citing it, a filing checklist, and title guidance drawn from existing issues.

Worked example

#128 was rewritten against this structure. It reads as the before/after: context establishes the run model and where PriceFn sits before naming any symptom, the problem section leads with a halted trajectory and walks back to pricing.py:53, and non-scope pushes failure postures to #129 and gateway model selection to #133 — both of which were previously implicit and would have been assumed in scope.

Notes

• Docs only, so it skips the open-an-issue-first step in CONTRIBUTING.md.
• No CHANGELOG.md entry: the Unreleased section tracks library changes, and this does not alter the package. Happy to add one if you would rather track contributor tooling there.
• In Claude Code, /raise-issue applies it; otherwise it reads as a plain checklist.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AVsDw5j9nQ2pgesFfW1yos