Resolve GitHub Issue

This skill guides you through resolving a GitHub issue for the sphinx-llm project using a test-driven development workflow.

Instructions

When the user asks you to resolve a GitHub issue, follow these steps:

1. Fetch Issue Information

First, retrieve the issue details:

If gh CLI is available:

gh issue view <issue-number> --repo NVIDIA/sphinx-llm

If the gh CLI is not available:

• Use an available web browsing or fetching tool to retrieve the issue from https://github.com/NVIDIA/sphinx-llm/issues/<issue-number>
• Extract the title, body, and labels

2. Check for a Readiness Label

IMPORTANT: Before proceeding with implementation, check if the issue has either the ready or good ai issue label. good ai issue is the project's label for issues that are well-defined enough to pass to a coding agent.

• If either label is present: Proceed with implementation
• If neither label is present: Stop and inform the user:

  "This issue does not have a ready or good ai issue label, which indicates it likely requires more discussion before implementation. Please ensure the issue has been discussed and approved by maintainers before proceeding."

3. Test-Driven Development Workflow

Once you've confirmed the issue is ready for implementation, follow this TDD workflow:

Step 3a: Write Tests First

• Review the existing test structure in src/sphinx_llm/tests/
• Write new test(s) that verify the desired functionality described in the issue
• The tests should fail initially (since the feature isn't implemented yet)

• Run the tests to confirm they fail as expected:

  uv run pytest src/sphinx_llm/tests/ -v

Step 3b: Implement the Feature

• Implement the minimum code necessary to make the tests pass
• Follow the project's architecture patterns (see AGENTS.md)

• Run tests frequently to verify progress:

  uv run pytest src/sphinx_llm/tests/ -v

• Ensure all tests pass before proceeding

Step 3c: Run Linting and Formatting

• Run pre-commit hooks to ensure code quality:

  pre-commit run --all-files

• Fix any issues identified by the linters

4. Update Documentation

After the implementation is complete and tests are passing:

• Update relevant documentation in docs/source/
• If the feature adds new configuration options, document them in the appropriate .rst files
• If the feature adds new directives or extensions, add examples to the docs

• Build the docs locally to verify changes:

  uv run --dev sphinx-build docs/source docs/build/html

Example Usage

User: "Resolve issue #42"

You should:

1. Run gh issue view 42 --repo NVIDIA/sphinx-llm (or use an available web browsing or fetching tool)
2. Check for a ready or good ai issue label
3. If either label is present, write tests in src/sphinx_llm/tests/
4. Implement the feature
5. Update docs in docs/source/
6. Run tests and linting

Notes

• Follow the existing code style and patterns
• Keep changes focused on the specific issue
• Don't over-engineer - implement only what's needed for the issue