---
name: glab-issue-audit
description: >
  Audit open GitLab issues for label compliance, board placement, and template conformance.
  Use when the user says /glab-issue-audit, /issue-audit, 'audit des tickets',
  'audit issues', 'check labels', 'vérifie les tickets', 'label audit',
  or wants to verify issue hygiene across Pysae projects.
argument-hint: "[--project PROJECT] [--all-projects] [--me] [--user NAME] [--search TERM] [--scope labels|board|title|template|all] [--fix] [--top N] [--console]"
allowed-tools:
  - Read
  - Bash
  - AskUserQuestion
---

Audit all open GitLab issues in the Pysae group (or a specific project) for compliance with Pysae conventions, and optionally fix violations.

## Required tools

- `glab`
- `jq`

Run `pysae-ai-tools tools require <tools>` before starting; if it exits non-zero, abort and report the install command from stderr to the user.

## Mode detection

Detect the execution context using `detect_context`:
```bash
CTX=$(pysae-ai-tools internal detect-context)
IS_CI=$(echo "$CTX" | jq -r '.is_ci')
PROJECT_ID=$(echo "$CTX" | jq -r '.project_id // empty')
PROJECT_PATH=$(echo "$CTX" | jq -r '.project_path // empty')
```

In CI mode (`IS_CI` is `true`):
- **Never use `AskUserQuestion`** — run the audit in `--console` mode automatically (no web UI)
- Print results to stdout and exit with code 1 if violations are found
- Use `PROJECT_ID` / `PROJECT_PATH` to scope the audit to the current project

## What is audited

1. **Labels** — only group-level labels (pysae group) are allowed. Project-level labels are forbidden.
2. **Board placement** — every open issue MUST have exactly one board column label (`workflow::Refinement`, `workflow::Ready`, `workflow::To Do`, `workflow::In progress`, `workflow::Under review`, `workflow::To deploy`).
3. **Weight** — every open issue MUST have a weight (story points) assigned.
4. **Template conformance** — the issue description must contain the required sections from one of the issue templates (`bug`, `feature`, `technical`). Exact heading match (emoji + casing). Additional sections are allowed, but the template sections must be present.
5. **Title** — must be in English, action-oriented (starts with a verb), and have no scope/type prefix like `[API]`, `tech:`, `feat:` (labels handle scoping).

## Usage

Run the audit script:

```bash
pysae-ai-tools glab issue-audit [OPTIONS]
```

### Options

| Flag | Description |
|------|-------------|
| `--project PROJECT` | Audit a specific project (e.g. `pysae/api` or `api`). Default: all group projects |
| `--all-projects` | Audit all group projects (overrides `--project`) |
| `--me` | Only audit issues assigned to the current user |
| `--user NAME` | Only audit issues assigned to a specific user (fuzzy name match) |
| `--search TERM` | Filter issues by title/description keyword (repeatable) |
| `--scope SCOPE [SCOPE...]` | Which checks to run: `default` (labels+board+weight), `all`, or specific: `labels`, `board`, `weight`, `title`, `template`. Can combine: `--scope labels title` |
| `--fix` | Apply auto-fixes for fixable violations (default: report only) |
| `--top N` | Limit output to the N most problematic issues (default: all) |
| `--console` | Console-only output, skip web UI (default: launches web UI) |

### Examples

```bash
# Audit all checks (report only)
pysae-ai-tools glab issue-audit

# Audit only title and label checks
pysae-ai-tools glab issue-audit --scope labels title

# Audit and fix labels + board
pysae-ai-tools glab issue-audit --scope labels board --fix

# Audit and fix everything
pysae-ai-tools glab issue-audit --fix

# Audit a specific project, fix titles
pysae-ai-tools glab issue-audit --project pysae/api --scope title --fix
```

## Process

1. **Run the audit script** with the options parsed from `$ARGUMENTS`:
   ```bash
   pysae-ai-tools glab issue-audit [OPTIONS]
   ```
   By default, this starts a detached web server (if not already running) and opens the browser. Pass `--console` to skip the web UI.

2. **Present the summary** to the user — show the top-level counts. The full detail is in the HTML report.

3. **Fix from browser** — when the user clicks "Fix" on an issue in the HTML report, the server spawns a new `claude -p` subprocess that runs this skill with `--fix --issue <project>#<iid>`. The fix runs autonomously.

4. **Fix from CLI** — `--fix` flag applies fixable corrections directly in batch mode:
   - **labels**: `glab api -X PUT` with `remove_labels` / `add_labels`
   - **board**: add Refinement, or keep the most advanced label if multiple
   - **title**: generate a proper English title (Claude does it in-session, no subprocess)
   - **template**: rename fuzzy-matching headings, append missing sections

## Rules

- The script **never deletes** issues or labels — it only adds/replaces labels, updates descriptions, and renames titles
- When promoting a project label to group level, the script looks for an exact name match in group labels
- When no group equivalent exists for a project label, the label is removed
- The default board label for issues missing one is `workflow::Refinement`
- Template detection uses the `type::` label to determine which template to check against. If no type label is present, template conformance is skipped for that issue
- Template fix: fuzzy-matches existing headings (same text without emoji or different casing) and renames them; missing sections are appended empty at the end
- Title fix: Claude generates the title directly in the current session — never use subprocess `claude --print`

$ARGUMENTS
