Skip to content

Commit a54cbc6

Browse files
josecelanojosecelano
committed
docs(issues): add issue specification for torrust#1774 
1 parent ec39f8e commit a54cbc6

1 file changed

Lines changed: 151 additions & 0 deletions

File tree

‎docs/issues/open/1774-automate-cleanup-completed-issues-skill-script.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
doc-type: issue
3+
issue-type: enhancement
4+
status: planned
5+
priority: p2
6+
github-issue: 1774
7+
spec-path: docs/issues/open/1774-automate-cleanup-completed-issues-skill-script.md
8+
branch: "1774-automate-cleanup-completed-issues-skill-script"
9+
related-pr: null
10+
last-updated-utc: 2026-05-13 12:40
11+
semantic-links:
12+
skill-links:
13+
- create-issue
14+
related-artifacts:
15+
- .github/skills/dev/planning/cleanup-completed-issues/SKILL.md
16+
- docs/issues/open/README.md
17+
- docs/issues/closed/README.md
18+
---
19+
20+
<!-- skill-link: create-issue -->
21+
22+
# Issue #1774 - Automate cleanup of completed issue specs with a non-interactive script
23+
24+
## Goal
25+
26+
Automate the cleanup workflow for completed issue specs so moving closed issue specs from open to closed is fast, safe, and consistent for both humans and agents.
27+
28+
## Background
29+
30+
The workflow in .github/skills/dev/planning/cleanup-completed-issues/SKILL.md is clear but currently manual. Batch cleanup is repetitive and increases the chance of mistakes, especially when validating issue state and selecting the correct files.
31+
32+
The documented lifecycle already defines a safe two-stage process:
33+
34+
1. Stage 1 archive: move closed issue specs from docs/issues/open/ to docs/issues/closed/
35+
2. Stage 2 delete: remove old specs from docs/issues/closed/ only when no longer referenced
36+
37+
This issue starts with Stage 1 automation and leaves Stage 2 deletion safeguards as a follow-up task in the same implementation scope.
38+
39+
## Scope
40+
41+
### In Scope
42+
43+
- Add script-based automation for Stage 1 archive.
44+
- Keep script execution non-interactive and agent-friendly.
45+
- Default to dry-run and require explicit apply mode for file changes.
46+
- Verify GitHub issue state before moving files.
47+
- Produce structured JSON results on stdout and diagnostics on stderr.
48+
- Update cleanup skill documentation with script usage and examples.
49+
50+
### Out of Scope
51+
52+
- Automatically deleting files from docs/issues/closed/ without reference checks.
53+
- Broad docs/issues taxonomy changes.
54+
- Unrelated issue lifecycle process changes.
55+
56+
## Implementation Plan
57+
58+
Status values: TODO, IN_PROGRESS, BLOCKED, DONE.
59+
60+
| ID | Status | Task | Notes / Expected Output |
61+
| --- | ------ | ------------------------------------ | ------------------------------------------------------- |
62+
| T1 | TODO | Define script interface | Flags, exit codes, output format, and error contract |
63+
| T2 | TODO | Implement Stage 1 archive automation | Closed-state verification and deterministic file moves |
64+
| T3 | TODO | Add safety and idempotency checks | Re-runnable behavior with clear skip reasons |
65+
| T4 | TODO | Update skill documentation | SKILL.md includes script inventory, usage, and examples |
66+
| T5 | TODO | Validate quality gates | linter all and targeted checks pass |
67+
68+
## Progress Tracking
69+
70+
### Workflow Checkpoints
71+
72+
- [x] Spec drafted in docs/issues/drafts/
73+
- [x] Spec reviewed and approved by user/maintainer
74+
- [x] GitHub issue created and issue number added to this spec
75+
- [ ] (Optional, recommended for complex issues) Spec-only PR merged into develop before implementation
76+
- [ ] Implementation completed
77+
- [ ] Automatic verification completed (linter all, relevant tests, and any pre-push checks)
78+
- [ ] Manual verification scenarios executed and recorded (status + evidence)
79+
- [ ] Acceptance criteria reviewed after implementation and updated with evidence
80+
- [ ] Reviewer validated acceptance criteria and updated checkboxes
81+
- [ ] Committer verified spec progress is up to date before commit
82+
- [ ] Issue closed and spec moved from docs/issues/open/ to docs/issues/closed/
83+
84+
### Progress Log
85+
86+
- 2026-05-13 12:20 UTC - Copilot - Created GitHub issue #1774 for cleanup automation.
87+
- 2026-05-13 12:40 UTC - Copilot - Added open issue spec file for #1774 in docs/issues/open.
88+
89+
## Acceptance Criteria
90+
91+
- [ ] AC1: Stage 1 archive flow is automated with non-interactive CLI execution.
92+
- [ ] AC2: Script defaults to dry-run and requires explicit apply mode for writes.
93+
- [ ] AC3: Only closed GitHub issues are eligible for move; open/not-found issues are skipped with actionable diagnostics.
94+
- [ ] AC4: Script output is machine-parsable JSON on stdout with per-issue outcomes.
95+
- [ ] AC5: Cleanup skill documentation is updated with script usage and constraints.
96+
- [ ] linter all exits with code 0
97+
- [ ] Relevant tests pass
98+
- [ ] Manual verification scenarios are executed and documented (status + evidence)
99+
- [ ] Acceptance criteria are re-reviewed after implementation and reflect actual behavior
100+
- [ ] Documentation is updated when behavior/workflow changes
101+
102+
## Verification Plan
103+
104+
Define verification before implementation starts and execute it before closing the issue.
105+
106+
### Automatic Checks
107+
108+
- linter all
109+
- Relevant tests for changed components
110+
- Pre-push checks (when applicable)
111+
112+
### Manual Verification Scenarios
113+
114+
Status values: TODO, IN_PROGRESS, DONE, FAILED, BLOCKED.
115+
116+
| ID | Scenario | Command/Steps | Expected Result | Status | Evidence |
117+
| --- | ---------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ | ------ | -------- |
118+
| M1 | Dry-run with closed and open issue | Run script with --issues containing one closed and one open issue | Closed issue marked movable; open issue skipped with reason | TODO | |
119+
| M2 | Apply mode with closed issue | Run script with --apply for one closed issue with file in docs/issues/open/ | File is moved to docs/issues/closed/ and result is reported | TODO | |
120+
| M3 | Idempotent rerun | Re-run the same command after successful move | Script reports already-moved or skipped without failing | TODO | |
121+
| M4 | Missing file behavior | Run script for a closed issue without matching file in docs/issues/open/ | Script exits non-zero or reports explicit missing-file error | TODO | |
122+
123+
Notes:
124+
125+
- Manual verification is mandatory even when automated tests pass.
126+
- If a scenario fails, record the failure and diagnosis in the progress log before proceeding.
127+
128+
### Acceptance Verification
129+
130+
| AC ID | Status (TODO/DONE) | Evidence |
131+
| ----- | ------------------ | -------- |
132+
| AC1 | TODO | |
133+
| AC2 | TODO | |
134+
| AC3 | TODO | |
135+
| AC4 | TODO | |
136+
| AC5 | TODO | |
137+
138+
## Risks and Trade-offs
139+
140+
- Script complexity could exceed the value for small batches.
141+
- Mitigation: keep MVP focused on Stage 1 archive and clear CLI boundaries.
142+
- Incorrect file matching could move wrong files.
143+
- Mitigation: strict issue-number-based matching and explicit ambiguity errors.
144+
- Over-automation could encourage unsafe deletion patterns.
145+
- Mitigation: keep Stage 2 deletion guarded and explicit, not implicit.
146+
147+
## References
148+
149+
- GitHub issue: https://github.com/torrust/torrust-tracker/issues/1774
150+
- Cleanup skill: .github/skills/dev/planning/cleanup-completed-issues/SKILL.md
151+
- Script guidance: https://agentskills.io/skill-creation/using-scripts

0 commit comments

Comments
 (0)