Skip to content

Jgocunha/dynamic-neural-field-composer / .claude/skills/work-an-issue

work-an-issue

Verified

End-to-end workflow for resolving one GitHub issue in dynamic-neural-field-composer - branch, TDD, build, review, docs, PR. Use when asked to fix, implement, or close a specific issue number.

FileKindSize
SKILL.mdskill md4.9 KB
---
name: work-an-issue
description: End-to-end workflow for resolving one GitHub issue in dynamic-neural-field-composer - branch, TDD, build, review, docs, PR. Use when asked to fix, implement, or close a specific issue number.
---

# Work an issue

One issue, one branch, one PR. Do not stack unrelated changes.

## 1. Understand

```bash
gh issue view <N> --comments
```

Restate in your own words: the goal, and the **success criterion** - the observable thing
that will be true when this is done. If you cannot state a success criterion, the issue is
too vague to work unattended; stop and say so.

## 2. Branch

Never commit to `main`. Branch from an up-to-date base:

```bash
git fetch origin
git switch -c <type>/<slug> origin/main
```

Branch type is one of `bug/ feat/ chore/ ci/ docs/ test/ refactor/`. Keep the slug short
and specific: `bug/connection-dim-check`, not `bug/fix-the-connection-dimension-problem`.

## 3. Failing test first

Write the test that reproduces the bug or specifies the feature. Add it to
`tests/CMakeLists.txt` if it is a new file. Build and **watch it fail** - a test that passes
before you have implemented anything is testing nothing.

Follow the suite's existing conventions: `EXPECT_NEAR` with an explicit tolerance for
floating point, file-local `makeField`/`makeStimulus` helpers rather than a shared header,
fixtures with `SetUp`/`TearDown` for anything touching the filesystem.

## 4. Instrument before theorising

If the failing test does not immediately tell you *why*, *do not reason about the control
flow by reading source*. Add logging, run it, and read what actually happened:

```cpp
tools::logger::log(tools::logger::DEBUG,
    "field 'u' step 42: max activation 0.87 at index 51, below threshold 1.0, no bump");
```

Write messages as plain natural-language sentences carrying the values that matter. Guessing
at the flow costs more than instrumenting it. Remove the instrumentation before the PR
unless it earns a permanent place at `DEBUG`.

## 5. Implement

Minimally. The smallest change that makes the test pass and nothing more.

Before writing any helper function, **search `tools/` first** - `math.h`, `utils.h`,
`profiling.h`, `logger.h`, `fft_convolution.h`, and `exceptions/exception.h`. If something
close already exists, extend or reuse it. A new free function duplicating an existing helper
will be rejected in review.

## 6. Build and test

Use the `build-and-test` skill. Green means the full suite, not just your new test.

## 6b. Performance check

If the diff touches the simulation hot path — `src/elements/`, `src/simulation/`, `src/tools/`,
`include/tools/math.h`, `include/tools/fft_convolution.h`, `include/tools/simd_dispatch.h` —
use the `perf-regression-test` skill.

Skip it otherwise, and say you skipped it. A silent skip reads as a pass.

An inconclusive result (too noisy, or no baseline for this machine) is not a pass. Report it as
unverified rather than moving on quietly.

## 7. Review your own diff

Use the `project-code-review` skill on `git diff origin/main...HEAD`. Fix what it finds
before asking anyone else to look.

## 8. Docs

Use the `docs-check` skill. Doxygen on new public API, wiki page for user-visible changes,
and no stale references left behind.

## 9. Changelog

Add an entry under `[Unreleased]` in the repo-root `CHANGELOG.md` — the one beside
`README.md`, not inside `dynamic-neural-field-composer/`. Create the `[Unreleased]` heading
if the last release consumed it.

Pick the subsection matching the work; the file uses `Added`, `Changed`, `Fixed`,
`Removed`, `Performance`, `Tests`, `Documentation`, `Build` and `CI`. Create it in that
order if absent.

Write for someone reading the release notes months from now with no access to the issue:
what changed, and why it mattered. Reference the issue as `(#N)`. Match the surrounding
entries' density — they are full sentences, not one-line summaries.

Every issue gets an entry, CI- and test-only work included. It is easier to drop a line at
release time than to reconstruct one from a diff.

## 10. Ship

```bash
git add -A && git commit -m "<type>: <lowercase summary>"
git push -u origin <branch>
gh pr create --title "<type>: <summary>" --body "<what / why / how to verify>

Closes #<N>"
```

Do **not** merge. The PR waits for human review.

## 11. Hand back

Report: PR URL, what changed, what you verified (with the test count), and anything you
deliberately left out.

## Stop conditions

Stop and ask rather than guessing when:

- **Backwards compatibility cannot be preserved.** This is never your call to make alone.
- The issue admits two readings that would produce materially different work.
- Tests fail for reasons unrelated to your change - report the pre-existing failure, do not
  paper over it or "fix" it as a side quest.
- The fix requires a design or product decision the issue does not settle.

When you stop, say exactly what you completed, what is blocked, and what you need.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall