organize

What this skill does

<!-- Governing: ADR-0015 (Markdown-Native Configuration), SPEC-0014 REQ "Config Resolution Pattern" -->

# Organize Issues into Projects

You are retroactively grouping existing tracker issues into tracker-native projects and enriching project workspaces. You use a three-tier intervention model that lets the operator control how invasive the changes are. See ADR-0012 and SPEC-0011.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the spec directory. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module. The resolved spec directory is `{spec-dir}`.

1. **Parse arguments**: Extract from `$ARGUMENTS`:
   - Spec identifier: a SPEC number (e.g., `SPEC-0007`) or capability directory name
   - `--project <name>`: Use a single combined project with this name for all issues. Default: per-epic.
   - `--dry-run`: Preview what would be created without making changes. Default: off.
   - `--module <name>`: Resolve artifact paths relative to the named module. Default: none.

   If no spec identifier is provided, list available specs by globbing `{spec-dir}/*/spec.md`, read the title from each, and use `AskUserQuestion` to ask which spec to organize.

2. **Resolve spec**: Follow the plugin's `references/shared-patterns.md` § "Spec Resolution" (which uses `{spec-dir}` from the Artifact Path Resolution pattern).

3. **Read spec**: Read `{spec-dir}/{capability-name}/spec.md` and `design.md` to understand the spec number, requirement names, and architecture. Validate spec pairing per `references/shared-patterns.md` § "Spec Pairing Validation".

4. **Detect tracker**: Follow the "Config Resolution" and "Tracker Detection" flows in the plugin's `references/shared-patterns.md`. Also read `Projects` settings from the `### SDD Configuration` section in CLAUDE.md for cached project IDs and enrichment config (Views, Columns, Iteration Weeks). If no tracker is found, error — projects require a tracker.

5. **Find existing issues**: Search the tracker for issues whose body references the spec number.
   - **GitHub**: `gh issue list --search "SPEC-XXXX" --json number,title,body,labels --limit 100`
   - **Gitea**: Use MCP tools (use `ToolSearch` to discover `list_repo_issues` or similar)
   - **GitLab**: Use MCP tools or `glab issue list --search "SPEC-XXXX"`
   - **Jira**: Use MCP tools to search issues with JQL containing the spec number
   - **Linear**: Use MCP tools to search issues containing the spec number
   - **Beads**: No-op — Beads epics ARE the grouping, so inform the user and exit

6. **Identify epics vs stories**: Classify each found issue:
   - **Epics**: Issues with titles starting with "Implement " or that have an `epic` label
   - **Stories**: All other issues referencing the spec

7. **Assess project state** (Governing: SPEC-0011 REQ "Organize Three-Tier Intervention"):

   For each project (existing or to-be-created), assess its current state:
   - Does the project exist? Is it linked to the repository?
   - Does it have a description? A README?
   - Does it have named views (GitHub: All Work, Board, Roadmap)?
   - Does it have an iteration/Sprint field (GitHub)?
   - Does it have board columns (Gitea: Todo, In Progress, In Review, Done)?
   - Does it have milestones for epics (Gitea)?
   - Are native dependency links set (Gitea)?
   - Are all issues correctly grouped and labeled?
   - Are `### Branch` and `### PR Convention` sections present in issue bodies?

   Present findings to the operator and offer **three intervention tiers** via `AskUserQuestion`:

   **(a) Leave as-is**: Report the current state and exit. No changes made.

   **(b) Restructure workspace only**: Add/fix project-level structure without touching any issues:
   - Create project if missing, link to repository
   - Add/update project description and README
   - Create/rename named views (GitHub)
   - Add iteration field (GitHub)
   - Create board columns (Gitea)
   - Create milestones (Gitea)
   - Add all issues to the project (if not already)

   **(c) Complete refactor**: All tier (b) changes PLUS:
   - Re-group issues across epics (move misplaced stories)
   - Fix/add labels using the try-then-create pattern (see `references/shared-patterns.md`)
   - Create native dependency links (Gitea)
   - Update issue bodies with `### Branch` and `### PR Convention` sections (if missing)

8. **Execute chosen tier**: Carry out the selected intervention. All enrichment steps use **graceful degradation**: if a feature is unavailable for the tracker, skip and log "Skipped {step}: {tracker} does not support {feature}".

   **GitHub workspace enrichment (tier b/c):**
   - Set project description referencing the spec
   - Write project README via GraphQL (agent-navigable context with spec refs, ADR links, story index, dependencies)
   - Create "Sprint" iteration field via GraphQL with cycle length from CLAUDE.md `Projects > Iteration Weeks` (default: 2 weeks)
   - Create named views via GraphQL using CLAUDE.md `Projects > Views` (default: "All Work" table, "Board" board, "Roadmap" roadmap)

   **Gitea workspace enrichment (tier b/c):**
   - Create milestones (one per epic), assign stories to milestones
   - Configure board columns from CLAUDE.md `Projects > Columns` (default: Todo, In Progress, In Review, Done)

   **Tier (c) additional steps:**
   - Re-label issues using the try-then-create pattern (see `references/shared-patterns.md`)
   - Create Gitea native dependency links
   - Add `### Branch` / `### PR Convention` to issue bodies that lack them (same logic as `/sdd:enrich`)

9. **`--dry-run` mode**: If `--dry-run` is set, report the assessment and what WOULD be done at each tier, but don't modify anything.

10. **Report results**: Provide a summary:
    - Tier selected and actions taken
    - Number of projects created, enriched, or reused
    - Number of issues organized/updated
    - Skipped enrichments (graceful degradation)
    - Any failures encountered (with issue numbers)
    - Whether CLAUDE.md `Projects` section was updated with project IDs

### Step 0a: Tier 4 issues sync (v5.0.0+)

<!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills" -->

Before discovering existing issues (Step 5), sync the `{repo}-issues` qmd collection from the tracker so the local cache reflects current issue state. This is Tier 4 of the freshness model: always sync at consumer entry, subject to a 5-minute deduplication window.

1. Read `.sdd/issues/_meta.json` (per `references/tracker-sync.md` § "Cursor Management"). If `last_sync` is within the last 5 minutes, skip the sync and proceed silently.
2. Otherwise, invoke the per-tracker fetch+normalize per `references/tracker-sync.md` with the cursor for incremental fetch. Print: "Syncing N issues from {tracker}…".
3. On sync failure, surface a one-line warning per `references/tracker-sync.md` § "Failure Modes and Degradation" and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; organize is the user's primary intent.

### Step 12: Tier 1 mutation update (v5.0.0+)

<!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 1 Mutation-Aware Updates" -->

After tier (c) interventions modify issue bodies (labels, project links surfaced in body, etc.), trigger a narrow re-sync of `{repo}-issues` so the qmd index reflects the changes. Use the canonical update pattern from `references/qmd-helpers.md` § "Update Patterns".

1. Re-fetch the modified issues via per-tracker fetch+normalize (only those touched in tier (c)).
2. Run `qmd update`.
3. Best-effort and silent on success. On failure, append a one-line warning ("Index refresh failed for `{repo}-issues` — run `/sdd:index update` manually") and report the organize step itself as successful.

If tier (a) (report-only) o