---
name: repo-issues
description: Manage repository-local issues using /meta/issues.md, /meta/issues_archive.md, and detailed issue files in /meta/issues/.
compatibility: opencode
metadata:
  category: workflow
  scope: repository
---

# Repository Issues

Use this skill when the user wants to create, inspect, work on, complete, or archive issues tracked inside the repository instead of an external issue tracker.

## Repository Structure

The repository issue tracker lives under `meta/` at the repository root:

```text
meta/
  issues.md
  issues_archive.md
  issues/
    <issue-slug>.md
```

If `meta/`, `meta/issues.md`, `meta/issues_archive.md`, or `meta/issues/` do not exist, create them before adding or updating issues.

## Index Rules

`meta/issues.md` is the open issue index. It must contain only currently open issues.

`meta/issues_archive.md` is the completed issue index. It must contain completed issues that were moved out of `meta/issues.md`.

Both index files should be checklist lists of linked issue titles:

```markdown
- [ ] [Issue title](issues/issue-title.md)
- [x] [Completed issue title](issues/completed-issue-title.md)
```

Rules:

1. Keep requirements, acceptance criteria, implementation notes, and discussion out of the index files.
2. Put the full issue body in `meta/issues/<issue-slug>.md` and link to it from the index.
3. Use `- [ ]` for open issues in `issues.md`.
4. Use `- [x]` for completed issues in `issues_archive.md`.
5. Do not duplicate the same issue in both index files.
6. Do not delete issue detail files when archiving. The archive should continue linking to the same detail file.

## Issue Detail Format

Issue detail files should be plain Markdown. Prefer this structure for new issues:

```markdown
# Issue title

## Summary

<short description of the problem or goal>

## Requirements

- <requirement>

## Acceptance Criteria

- <criterion that proves completion>

## Notes

- <optional context, constraints, links, or decisions>
```

Keep the detail file focused on the issue itself. Avoid copying the whole implementation history into it unless the user asks for that.

## Creating Issues

When creating a new issue:

1. Identify the repository root before writing under `meta/`.
2. Create a lowercase kebab-case slug from the issue title, such as `fix-login-timeout.md`.
3. If the slug already exists, choose the smallest clear variant, such as `fix-login-timeout-2.md`, unless the existing issue is the same issue.
4. Write the full issue text to `meta/issues/<slug>.md`.
5. Add exactly one open checklist entry to `meta/issues.md` linking to the detail file.
6. Do not add the new issue to `meta/issues_archive.md`.

## Working Issues

When asked to handle an existing issue:

1. Read `meta/issues.md` and identify the matching open issue.
2. If the user's request is ambiguous, ask which issue to handle.
3. Read the linked detail file before making code changes.
4. Implement the smallest correct change that satisfies the requirements and acceptance criteria.
5. Run relevant tests, checks, or builds when feasible.
6. If acceptance criteria cannot be verified, keep the issue open and report the blocker.

Do not mark an issue completed only because code was changed. Mark it completed only after the acceptance criteria are satisfied or the user explicitly says to close/archive it.

## Completing Issues

When an issue is done:

1. Confirm the implementation satisfies the issue detail file's acceptance criteria.
2. Move the issue's checklist entry from `meta/issues.md` to `meta/issues_archive.md`.
3. Change the moved checklist marker from `- [ ]` to `- [x]`.
4. Preserve the same linked title and detail file path.
5. Ensure `meta/issues.md` no longer contains the completed issue.
6. Leave the detail file in `meta/issues/`.

If verification was skipped or impossible, mention that clearly in the final response.

## Maintenance

When maintaining the issue tracker:

1. Keep links relative to `meta/`, for example `issues/my-issue.md`.
2. Keep open issues sorted according to the repository's existing convention. If there is no convention, append new issues to the end.
3. Preserve user-written wording in issue titles and detail files unless updating it is necessary.
4. Do not use GitHub, Jira, Linear, or other external trackers unless the user explicitly asks.
5. If an issue is closed as obsolete or duplicate, move it to the archive only when the user explicitly confirms closure.

## Final Response

After handling an issue, summarize:

1. Which issue was handled.
2. What changed.
3. What verification was run.
4. Whether the issue was archived or remains open.