agentleFS
jarosser06jarosser06/drift/.claude/skills/issue-writing/SKILL.md

issue-writing

Skill1 starsChanged 11 months agoMITView on GitHub

Expert in creating well-structured GitHub issues with clear problem statements, specific acceptance criteria, and actionable technical context using GitHub MCP. Specializes in feature requests, bug reports, and refactoring tasks with proper labels and issue tracking. Use when creating issues before implementation, reporting bugs, or structuring project work.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. Hambaobao/hambaobao-skills★ 2same name
    2. SaKaNa-Y/skills★ 2same name
    3. halkn/skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository12 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When multiple approaches exist, mention them:

    line 235
  2. Distinctive:

    Always include testing and documentation:

    line 299

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Issue Writing Skill

Learn how to create well-structured, actionable GitHub issues using the GitHub MCP server.

Issue Templates

Standard Template

## Problem Statement

[Describe the problem or need from user perspective]
[Include current workarounds if any]
[Explain impact and who is affected]

## Proposed Solution

[Describe the solution approach]
[Include command examples or usage patterns]
[List what the tool should do]

## Acceptance Criteria

- [ ] [Specific testable criterion 1]
- [ ] [Specific testable criterion 2]
- [ ] [Specific testable criterion 3]
- [ ] Unit tests added with 90%+ coverage
- [ ] Integration tests cover end-to-end flow
- [ ] README updated with usage examples
- [ ] Error messages guide users on common issues

## Technical Notes

[Implementation approach if known]
[Edge cases to handle]
[Backward compatibility requirements]
[Error handling requirements]

## Related Issues

[Only include if there are actual related issues with issue numbers]

Bug Report Template

## Problem Statement

[Describe the bug and its impact]

Steps to reproduce:
1. [Step 1]
2. [Step 2]
3. [Observed error]

Expected: [Expected behavior]
Actual: [Actual behavior]

Impact: [Who is affected and how]

## Proposed Solution

[How to fix the bug]
[What changes are needed]

## Acceptance Criteria

- [ ] Bug fixed
- [ ] Root cause addressed
- [ ] Tests prevent regression
- [ ] Error messages improved if relevant

## Technical Notes

[Where the error occurs]
[Root cause if known]
[Edge cases to test]

## Related Issues

[Only include if there are actual related issues with issue numbers]

How to Write Effective Issues

How to Structure an Issue

A well-structured issue includes:

  1. Problem Statement - What problem needs solving
  2. Proposed Solution - How to address it
  3. Acceptance Criteria - How to know when it's done
  4. Technical Notes - Important constraints or considerations
  5. Related Issues - Links to related work

Example:

## Problem Statement

The CLI currently only supports analyzing a single drift type per run.
Users need to analyze multiple drift types in one execution to avoid
running the tool multiple times on the same conversation log.

## Proposed Solution

Add support for specifying multiple --drift-type arguments. The tool
should perform multi-pass analysis, running each drift type detection
separately and combining results in the output.

## Acceptance Criteria

- [ ] CLI accepts multiple --drift-type arguments
- [ ] Each drift type runs in separate LLM call
- [ ] Results are combined in single output
- [ ] Tests cover multi-type analysis
- [ ] Documentation updated with examples

## Technical Notes

- Maintain separate LLM calls per drift type (don't combine in single prompt)
- Consider rate limiting for multiple API calls
- Output format should clearly separate results by type
- Config merge should work with multiple types

## Related Issues

- Relates to #15 (configuration improvements)
- Blocks #22 (batch processing feature)

How to Write Problem Statements

Focus on User Impact

Good - explains the problem:

## Problem Statement

The CLI currently only supports analyzing a single drift type per run.
Users must run the tool multiple times on the same log to check for
different drift patterns, which is slow and inefficient.

This impacts workflows where users want comprehensive analysis
(e.g., CI/CD pipelines checking all drift types).

Avoid implementation details:

## Problem Statement

The drift_type variable is a string instead of a list, and the
detector.analyze() method only accepts one type at a time.

Why it's better: Users care about the problem (slow, inefficient), not the implementation detail (string vs list).

Provide Context

Good - includes context:

## Problem Statement

Users report config parsing fails with KeyError when .drift.yaml
is missing the drift_types section. This happens in:
- Fresh project setups without full config
- Minimal config files for testing
- Projects using only CLI args, not config

Expected behavior: drift_types should be optional with sensible defaults.

Avoid vague descriptions:

## Problem Statement

Config parsing doesn't work correctly.

Use Examples

Good - concrete example:

## Problem Statement

The output format is inconsistent. When analyzing multiple logs:

Current behavior:

Log 1: drift detected Log 2: no issues Log 3: error


This makes it hard to parse programmatically or integrate with CI/CD.

How to Write Proposed Solutions

Describe the Approach

Good - clear solution:

## Proposed Solution

Add support for multiple --drift-type arguments:

```bash
drift analyze log.json --drift-type incomplete_work --drift-type spec_adherence

The tool should:

  1. Parse multiple --drift-type flags
  2. Run separate LLM analysis for each type
  3. Combine results in unified output format
  4. Show clear separation by type in output

**Avoid over-specifying:**
```markdown
## Proposed Solution

Change cli.py line 45 to use drift_types as a list instead of string.
Add a for loop in detector.py around line 120 to iterate over types.
Update the DriftDetector.__init__() to accept List[str].

Why it's better: Suggests approach without dictating exact implementation. Leaves flexibility for better solutions discovered during implementation.

Consider Alternatives

When multiple approaches exist, mention them:

## Proposed Solution

Add caching to reduce duplicate API calls.

Options:
1. **In-memory cache** - Simple, works for single runs
2. **File-based cache** - Persists across runs, good for CI/CD
3. **Redis cache** - Distributed, best for multi-instance deployments

Recommend starting with #2 (file-based) as it balances simplicity and usefulness.

How to Write Acceptance Criteria

Make Them Testable

Good - specific and testable:

## Acceptance Criteria

- [ ] CLI accepts multiple --drift-type arguments
- [ ] Each drift type runs in separate LLM call
- [ ] Results combined in single JSON output
- [ ] Exit code is 1 if any drift type detects issues
- [ ] Tests cover multi-type analysis with 90%+ coverage
- [ ] README shows multi-type usage example

Avoid vague criteria:

## Acceptance Criteria

- [ ] Feature works correctly
- [ ] Code is tested
- [ ] Documentation updated

Focus on Outcomes

Good - outcome-focused:

## Acceptance Criteria

- [ ] Users can specify cache directory via --cache-dir flag
- [ ] Cached results are used when log file hasn't changed
- [ ] Cache can be cleared with --clear-cache flag
- [ ] Cache hit/miss stats shown in debug output

Avoid implementation details:

## Acceptance Criteria

- [ ] Add cache_dir parameter to Config class
- [ ] Implement _get_cache_key() method
- [ ] Add pickle serialization for results
- [ ] Create cache/ directory in project root

Include Quality Checks

Always include testing and documentation:

## Acceptance Criteria

- [ ] <Feature criteria 1>
- [ ] <Feature criteria 2>
- [ ] Unit tests added with 90%+ coverage
- [ ] Integration tests cover end-to-end flow
- [ ] README updated with usage examples
- [ ] Error messages guide users on common issues

How to Write Technical Notes

Highlight Constraints

Good - important constraints:

## Technical Notes

- Maintain backward compatibility - existing single --drift-type usage must still work
- Rate limiting: Add 1-second delay between API calls to avoid throttling
- Config validation: Validate drift types against supported list before analysis
- Error handling: If one type fails, continue with others and report partial results

Suggest Approaches

Good - helpful suggestions:

## Technical Notes

Potential implementation approaches:
1. Modify cli.py to accept multiple --drift-type flags (use action='append')
2. Create MultiPassAnalyzer class to orchestrate multiple detectors
3. Update output format to separate results by type (add "drift_type" field)

Consider:
- Using asyncio for parallel API calls (if rate limits allow)
- Caching to avoid re-analyzing same log multiple times

Point Out Edge Cases

## Technical Notes

Edge cases to handle:
- Empty drift_types list (should error or use defaults?)
- Duplicate drift types specified (de-duplicate or error?)
- Invalid drift type names (validate against supported list)
- Partial failures (one type succeeds, one fails)

Link to Relevant Code

## Technical Notes

Relevant code sections:
- `drift/cli.py:45-67` - Current single drift type parsing
- `drift/detector.py:120-145` - DriftDetector.analyze() method
- `drift/config.py:78-95` - Config drift_types validation

See #15 for related config improvements discussion.

How to Create Issues with MCP

Basic Issue Creation

mcp__github__create_issue(
    owner="jarosser06",
    repo="drift",
    title="Add multi-drift-type analysis support",
    body="""## Problem Statement

The CLI currently only supports analyzing a single drift type per run.
Users need to analyze multiple drift types in one execution to avoid
running the tool multiple times on the same conversation log.

## Proposed Solution

Add support for specifying multiple --drift-type arguments. The tool
should perform multi-pass analysis, running each drift type detection
separately and combining results in the output.

## Acceptance Criteria

- [ ] CLI accepts multiple --drift-type arguments
- [ ] Each drift type runs in separate LLM call
- [ ] Results are combined in single output
- [ ] Tests cover multi-type analysis
- [ ] Documentation updated with examples

## Technical Notes

- Maintain separate LLM calls per drift type (don't combine in single prompt)
- Consider rate limiting for multiple API calls
- Output format should clearly separate results by type

## Related Issues

- Relates to #15 (configuration improvements)
- Blocks #22 (batch processing feature)
""",
    labels=["enhancement"],
    assignees=[]
)

Issue with Labels and Assignment

issue = mcp__github__create_issue(
    owner="jarosser06",
    repo="drift",
    title="Fix config parser crash on missing drift_types",
    body="""## Problem Statement

Config parser crashes with KeyError when .drift.yaml is missing
the drift_types section, even though this should be optional.

## Proposed Solution

Add proper defaults and validation for config parsing.

## Acceptance Criteria

- [ ] Parser handles missing drift_types gracefully
- [ ] Uses built-in defaults when not specified
- [ ] Tests cover missing and invalid configs

## Technical Notes

- Error occurs in config.py:load_project_config()
- Should use built-in DRIFT_TYPES constant as default
""",
    labels=["bug", "priority:high"],
    assignees=["your-username"]
)

print(f"Issue created: {issue['html_url']}")

Examples by Issue Type

See Issue Examples for complete examples:

  • Feature request
  • Bug report
  • Refactoring task

How to Choose Labels

By type: bug, enhancement, documentation, refactoring, question

By priority: priority:high, priority:medium, priority:low

By area: cli, config, providers, testing

Example:

mcp__github__create_issue(
    owner, repo,
    title="Add caching support",
    body="...",
    labels=["enhancement", "performance", "priority:medium"]
)

Common Issue Workflows

See Issue Examples for workflows on:

  • Creating issue for new feature (4 steps)
  • Creating bug report (3 steps)

Resources

📖 Templates

Issue templates for standard and bug reports.

Use when: Creating a new issue and need structure.

📖 Issue Examples

Complete examples by issue type with workflows.

Use when: Need reference examples or workflow guidance.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.