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.

Work an issue

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

1. Understand

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:

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:

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

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: 471kUpdated 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