markuplint Input: $ARGUMENTS
Follow these steps in order:
Step 1: Understand the Problem
If a GitHub Issue URL is provided:
- Extract owner/repo/number from the Issue URL
- Run
gh issue view <URL> --json number,title,body,labels,comments,assignees,stateto retrieve all Issue details - Proceed to Step 2
If NO URL is provided (or input is empty/a keyword):
- Ask the user to describe the problem using AskUserQuestion or conversation:
- What is happening? (bug, feature request, refactoring, etc.)
- How to reproduce? (for bugs)
- What is the expected behavior?
- Which packages or rules are affected? (if known)
- Gather enough context to form a clear problem statement before proceeding
- Do NOT skip this step — do NOT guess or assume the problem
- Proceed to Step 1b
Step 1b: Register as a GitHub Issue (only when no URL was provided)
This step runs ONLY when no Issue URL was provided in Step 1.
Based on the information gathered from the user, create a GitHub Issue.
Use the repository's existing Issue templates (.github/ISSUE_TEMPLATE/) as the format reference:
- Determine the Issue type and match to an existing template:
- Bug →
bug_report.mdformat (label:Bug) - Feature request →
feature.mdformat (label:Features: Proposal) - Spec update →
update_specs.mdformat (label:Specs)
- Bug →
- Fetch available labels to avoid typos:
gh label list --limit 50 - Verify referenced paths and libraries exist (check paths with
ls, packages withnpm view) before putting them in the Issue body - Draft the Issue content following the matched template's structure — read the template file itself for the section layout
- Show the draft to the user and ask for confirmation before creating
- Create the Issue:
gh issue create --title "<title>" --body "<body>" --label "<label>" - Capture the Issue number and URL from the output for use in subsequent steps
- From this point forward, treat the newly created Issue the same as if it had been provided via URL
Step 2: Ensure You Are in a Worktree
CRITICAL: NEVER work in the main working directory.
Branch work happens in a Claude Code–managed worktree (see the Branch & Worktree Policy in the root CLAUDE.md). If this session is not already in one, set one up via the harness worktree feature before touching any file. Branch name: issue/<number>-<slug> (slug from title, lowercase, hyphens, max 50 chars — the Issue number is always available at this point). Remember the fresh-worktree setup: yarn install, then NX_WORKSPACE_ROOT_PATH=<worktree-absolute-path> yarn build.
Step 3: Analyze the Problem
Read through the Issue body and comments carefully, then organize the following:
- Summary: What is happening / what is being requested
- Reproduction: For bugs, reproduction steps and environment
- Related Code: Identify files, functions, and rules mentioned in the Issue and explore the codebase
- Impact Scope: Packages and features potentially affected by the fix
Step 4: Propose a Resolution Plan
Based on the analysis, present a resolution plan following TDD (Test-Driven Development):
- Approach: The chosen solution and rationale
- Files to Change: List of files to modify or add
- Implementation Steps: Follow the Red-Green cycle for each behavior unit:
- Red: Write failing tests first that define the expected behavior — as spec-file tests, never as throwaway reproduction scripts
- Green: Implement the minimal code to make the tests pass
- Risks: Side effects and caveats
Present the plan to the user and wait for approval.
Step 5: Hand Off to /impl
Once the plan is approved, continue with the impl skill — it owns the implementation pipeline (implement → review → QA → lint/test → commit → PR). Do not re-negotiate the agreed scope there.