yamcodes/arkenv/tackle-issue

Tackle issue

This skill provides a standardized, rigorous workflow for handling GitHub issues. It ensures that issues are properly vetted before work begins and that all changes meet the project's quality standards before a Pull Request is opened.

Trigger

Use this skill whenever the user says /tackle-issue <number> or asks to "tackle", "handle", or "fix" a specific issue number in a structured way.

Workflow

1. Readiness check & context gathering

Before starting any work, you MUST verify that the issue is ready for an agent.

1. Retrieve Issue Details: Fetch the issue context, including labels and comments.

``bash gh issue view <issue-number> --json title,body,labels,comments ``

1. Verify the issue can start: Check the labels array.

• If `blocked` is present: Abort the process immediately, even when ready for agent is also present. Inform the user: Issue #<number> is labeled 'blocked'. Work cannot start until that blocker clears.
• If `ready for agent` is MISSING: Abort the process immediately. Inform the user: Issue #<number> is not marked as 'ready for agent'. Please ensure it is fully specified and labeled correctly before proceeding.
• If `ready for agent` is present and `blocked` is not: Continue to the next step.

2. Development setup

1. Setup Development Branch: Create and checkout a linked development branch.

``bash gh issue develop <issue-number> --checkout `` Note: If a branch already exists, this command will switch to it.

3. Implementation

Proceed with the standard Research -> Strategy -> Execution lifecycle.

• Research: Understand the issue and surrounding code.
• Strategy: Plan the fix or feature.
• Execution: Apply changes surgically. Ensure that:
• New tests are added to verify the fix or feature.
• Relevant documentation is updated.
• JSDoc comments are added or updated for all new or modified functions according to the jsdoc skill.

4. Validation & quality assurance

Once implementation is complete, you MUST run the following validation suite in the project root:

1. Type Check:

``bash pnpm run typecheck ``

1. Test Suite:

``bash pnpm run test ``

1. Lint & Format Check:

``bash pnpm run fix ``

If this step fails (some lint/formatting issues cannot be auto-fixed), you MUST diagnose and fix the errors before proceeding.

5. Changeset creation

After validation passes, you MUST create a changeset using the changeset skill ONLY if your changes affect a published package, a private package, or anything that gets imported by other packages. Do not create a changeset if the changes are isolated strictly to playgrounds or examples.

• Determine the appropriate bump type (patch or minor for v0) based on the changeset guidelines.
• Provide a clear, concise description starting with a #### header.

6. Pull request creation

When the task is complete and validated:

1. Commit and Push: Stage all changes (including the changeset if created) and push.

``bash git add . git commit -m "fix: tackle issue #<issue-number>" git push -u origin HEAD ``

1. Create Pull Request:

• Title: Use fix: <issue-title> or feat: <issue-title>.
• Body: MUST include Fixes #<issue-number> to link the PR to the issue.
• Labels: Apply relevant labels from the original issue (excluding ready for agent).

``bash gh pr create --title "fix: <issue-title>" --body "Fixes #<issue-number>\n\n<brief-description-of-changes>" --label "<labels>" ``

Best practices

• Strict Readiness: Never bypass the ready for agent check. It ensures the task is well-defined.
• Validation First: Never open a PR that fails typecheck, test, or check.
• Link Everything: Always use gh issue develop and Fixes #<num> for traceability.
• Changesets: Include a changeset for changes affecting published packages, private packages, or anything imported by other packages. Avoid changesets when changes are isolated to playgrounds or examples.