Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/skills/dev/planning/create-issue/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,15 @@ Lifecycle docs:
4. **Move spec file to `docs/issues/open/`** and include the issue number
5. **Pre-commit checks** and commit the spec

For complex or high-impact issues, a **spec-first PR** is recommended:

- Open a branch containing only issue-spec/EPIC documentation changes
- Submit and merge that PR into `develop` first
- Start implementation only after the specification PR has been reviewed and merged

This improves visibility and allows maintainers/contributors to review scope and acceptance
criteria before code changes begin.

**Never create the GitHub issue before the user reviews and approves the specification.**

## Step-by-Step Process
Expand All @@ -63,6 +72,12 @@ explicitly during implementation:
- `Progress Tracking` (`Workflow Checkpoints` and first `Progress Log` entry)
- `Acceptance Criteria` and `Acceptance Verification`

The draft must also include a verification policy that is explicit and enforceable:

- Automatic checks to run after implementation (`linter all`, relevant tests, pre-push checks when applicable)
- Manual verification scenarios with status + evidence tracking (mandatory)
- A post-implementation acceptance criteria review step

Use **placeholders** for the issue number until after creation (for example `github-issue: null`
or `[To be assigned]` in the heading/body content).

Expand Down Expand Up @@ -114,6 +129,45 @@ git commit -S -m "docs(issues): add issue specification for #{number}"
git push {your-fork-remote} {branch}
```

### Optional Step 6 (Recommended for Complex Issues): Spec-Only PR

When the issue is complex, cross-cutting, or likely to need scope negotiation, open a PR that
contains only the issue specification changes:

1. Branch from `develop`
2. Commit only spec changes (`docs/issues/`, and if needed templates/skills)
3. Push branch to your fork remote (for example `josecelano`)
4. Open PR in the **upstream repository** (`torrust/torrust-tracker`) targeting `develop`
5. If using fork-based workflow, set head as `{fork-owner}:{branch}` (for example
`josecelano:1771-spec-first-pr-workflow`)
6. Do not open the PR in the fork repository unless explicitly requested
7. Merge PR after review
8. Start implementation work in a separate branch/PR

Recommended GitHub CLI command for fork-based PRs:

```bash
gh pr create \
--repo torrust/torrust-tracker \
--base develop \
--head {fork-owner}:{branch} \
--title "{title}" \
--body-file {body-file}
```

## Verification Requirements for Issue Specs

When creating or updating issue/epic specs, ensure these requirements are present in the spec
before implementation starts:

1. **Automatic verification**: list required automated checks.
2. **Manual verification**: define concrete manual scenarios with commands/steps and expected results.
3. **Evidence tracking**: include status/evidence fields for manual scenarios.
4. **Post-implementation AC review**: explicitly require acceptance criteria to be re-reviewed
against observed behavior before closing the issue.

Do not treat an issue as complete only because automated tests pass; manual validation is required.

## Naming Convention

File name format: `{number}-{short-description}.md`
Expand Down
Loading