implement-issue

name	implement-issue
description	Implement a GitHub issue on the current branch with complete validation, tests, and documentation updates.

Codex invocation: use $implement-issue or select this skill through /skills. References below to /implement-issue describe the source repository command.

Use this command when the user wants to implement an existing GitHub issue in the current repository and on the branch where the user already is.

The expected result is a complete local implementation of the issue, with source changes, required tests, relevant product and technical documentation updates, and all required validation gates executed.

Input

This command expects /implement-issue <issue-reference>.

<issue-reference> can be a GitHub issue number, issue URL, or unambiguous issue identifier for the current repository.

If no issue reference is provided, ask the user which GitHub issue to implement and stop.

Preconditions

Before changing files, verify that:

• the current GitHub repository can be identified;
• the current branch is not ambiguous and is the branch where the user wants the work implemented;
• the issue can be read through GitHub MCP, GitHub CLI gh, or another configured GitHub integration;
• the issue is open or otherwise explicitly intended for implementation;
• the working tree state is understood, including any existing user changes.

Use the most direct reliable GitHub integration available in this order:

• GitHub MCP when repository identity and issue reference are clear;
• GitHub CLI gh when MCP is unavailable or unsuitable;
• another configured GitHub integration only when it is the most reliable available option.

If the repository, branch, issue, or GitHub integration cannot be determined safely, report what is missing and stop before editing files.

If unrelated local changes already exist, preserve them. Do not revert, overwrite, or stage them unless the user explicitly asks.

Workflow

1. Resolve the issue reference from $ARGUMENTS and fetch the full issue title, body, labels, comments, linked references, and acceptance criteria.
2. Analyze the issue as the source of implementation scope. Identify expected behavior, out-of-scope boundaries, test requirements, documentation impact, risks, and missing decisions.
3. Ask the user only for decisions that cannot be inferred from the issue or repository evidence and that materially affect behavior, safety, scope, data, architecture, documentation, or validation.
4. Inspect the relevant files before editing. Include affected main, preload, renderer, shared, IPC, persistence, infrastructure, test, and documentation areas as applicable.
5. Implement the smallest correct change that satisfies the issue and follows the repository architecture and code standards.
6. Add or update tests for every changed boundary according to the docs. UI component and E2E tests must drive user-representative actions and assert user-visible outcomes by default; for rich interactions, the assertions must cover every visible dimension promised by the behavior, such as all affected chart axes, mode state, cursor/tooltip output, reset controls, synchronized followers, or rendered geometry. Direct store writes, component method calls, synthetic internal events, React fiber access, ECharts dispatchAction, ECharts setOption, or private runtime mutation are exceptions that require a documented blocker and separate coverage of the closest available user-visible flow. If manual rendered verification still fails while the automated UI test passes, strengthen the test before accepting the implementation. Mark user-visible behavior tests with @behavior <ID>, technical behavior tests with @technical-behavior <ID>, or local mechanics with @implementation according to docs/tech/behavior-contract-testing.md.
7. For bug fixes, add regression coverage. Prefer failing-first regression when practical.
8. Update product documentation under docs/product/** when user-visible behavior changes, a new feature is added, or a bug fix establishes, restores, or clarifies expected user-visible behavior that is missing, wrong, ambiguous, or not represented by a behavior ID in existing docs.
9. Update technical documentation under the appropriate docs/tech/** category when architecture, feature implementation, IPC/API contracts, test strategy, setup, tools, implementation guidance, or reusable technical constraints change.
10. For features and infrastructure changes, document the expected product behavior, technical rule, workflow, or persistence/setup contract after implementation.
11. For bug fixes, document the expected current behavior or reusable rule. Do not add historical notes that merely say the bug was fixed.
12. If no documentation update is required, identify the exact existing document section that already covers the behavior or explain why the change has no product, technical, workflow, template, or deferred-debt impact.
13. Create new documentation only when existing docs cannot absorb the topic without mixing scopes. Follow docs/how-to/documentation-writing-standards.md and docs/how-to/documentation-folder-structure.md, including reciprocal ## Related Documents links.
14. If the implementation changes AI assets under ai/**, run bash ai/sync-ai-files.sh and include the generated files.
15. Run validation from repository root according to docs/how-to/pre-merge-change-validation.md.
16. Use this default full validation order unless the issue scope justifies a smaller documented subset:

pnpm lint:fix
pnpm lint
pnpm typecheck
pnpm test:behavior-contracts
pnpm test:core
pnpm test:unit:renderer
pnpm test:integration
pnpm test:components
pnpm test:hooks
pnpm test:e2e
pnpm build

17. Run additional focused suites or pnpm test:e2e:compiled when the issue, changed boundaries, or packaging/runtime risk requires them.
18. If any validation gate fails, fix the root cause and rerun the failed gate plus any dependent gates affected by the fix.
19. Re-read the issue acceptance criteria and verify each item against the final diff, tests, and documentation.
20. Do not create commits, push, change branches, close the issue, or open a pull request unless the user explicitly asks.

Required output

Report:

• command result status;
• issue reference, title, and URL;
• current branch used for implementation;
• summary of implemented behavior;
• key decisions clarified or inferred from repository evidence;
• behavior contract IDs added or reused, or missing documentation decisions requested from the user;
• UI test actions and assertions used for user-visible behavior, including every visible interaction dimension covered, plus any documented internal-testing exceptions;
• documentation updated or skipped, with the reason;
• validation commands run and results, or commands skipped with the reason;
• final status and remaining risks or follow-up work.