---
name: audit-issue-conflicts
description: Use when asked to detect conflicting requirements or incompatible decisions across open issues.
disable-model-invocation: true
argument-hint: "[--auto] [--dry-run] [--cross-theme]"
model: sonnet
allowed-tools:
  - Read
  - Glob
  - Edit
  - Task
  - AskUserQuestion
  - Bash(git:*)
  - Bash(ll-issues:*)
arguments:
  - name: flags
    description: "Optional flags: --auto (apply all recommendations without prompting), --dry-run (report only, no changes), --cross-theme (add Phase 2b cross-batch fingerprint sweep to catch conflicts spanning thematic groups)"
    required: false
metadata:
  short-description: Use when asked to detect conflicting requirements or incompatible decisions acro
---

# Audit Issue Conflicts

You are tasked with scanning all open issues for semantic conflicts, synthesizing a ranked conflict report, and optionally applying recommended resolutions — either interactively (default), automatically (`--auto`), or as a report only (`--dry-run`).

## Configuration

This skill uses project configuration from `.ll/ll-config.json`:
- **Issues base**: `{{config.issues.base_dir}}`

---

## Phase 0: Parse Flags

```
AUTO_MODE = false
DRY_RUN = false
CROSS_THEME = false

# Auto-enable in automation contexts
if ARGUMENTS contains "--dangerously-skip-permissions" or env LL_NON_INTERACTIVE is set or env DANGEROUSLY_SKIP_PERMISSIONS is set: AUTO_MODE = true

# Explicit flags
if ARGUMENTS contains "--auto": AUTO_MODE = true
if ARGUMENTS contains "--dry-run": DRY_RUN = true
if ARGUMENTS contains "--cross-theme": CROSS_THEME = true
```

Log the active mode:
- `--auto` → "Running in auto-apply mode: all recommendations will be applied without prompting."
- `--dry-run` → "Running in dry-run mode: conflict report will be output, no files will be modified."
- `--cross-theme` → "Cross-theme sweep enabled: Phase 2b will check for conflicts spanning thematic batch boundaries."
- neither → "Running in interactive mode: each recommendation will require approval."

---

## Phase 1: Load Issues

Collect all active issue files:

```bash
declare -a ISSUE_FILES
declare -i TERMINAL_COUNT=0
for dir in {{config.issues.base_dir}}/{bugs,features,enhancements}/; do
    [ -d "$dir" ] || continue
    for f in "$dir"*.md; do
        [ -f "$f" ] || continue
        status=$(awk '/^---$/{n++; next} n==1 && /^status:/{print $2; exit}' "$f")
        case "${status:-open}" in
            open|in_progress|blocked) ISSUE_FILES+=("$f") ;;
            *) TERMINAL_COUNT=$((TERMINAL_COUNT + 1)) ;;
        esac
    done
done

if [[ ${#ISSUE_FILES[@]} -eq 0 ]]; then
    echo "No active issues found"
    exit 0
fi

echo "Found ${#ISSUE_FILES[@]} active issues (excluded $TERMINAL_COUNT terminal issues)"
```

For each file, parse from the filename:
- **ID** (e.g., `FEAT-1028`, `BUG-042`)
- **Type** (`BUG`, `FEAT`, `ENH`, `EPIC`)
- **Priority** (`P0`–`P5`)

Then read the file to extract:
- **Title** (from `# heading`)
- **Summary** section
- **Integration Map** / **Implementation Steps** / **Objectives** sections (first 300 chars each)

---

## Phase 2: Conflict Detection

Batch issues **3–5 per Task call**. Spawn all batch Task calls in a **single message** (parallel).

For each batch, use this prompt template:

```
Analyze the following issues for semantic conflicts.

You are looking for four conflict types:

1. **Requirement conflicts** — Issue A requires X, Issue B requires not-X (contradictory requirements)
2. **Objective conflicts** — Two issues solve the same problem but with different approaches (duplicated goal)
3. **Architecture conflicts** — Incompatible technical approaches (e.g., sync vs async, different data models, conflicting API shapes)
4. **Scope overlap** — Issues that partially duplicate each other's scope (overlapping but not identical)

For EACH pair of issues in this batch, determine if a conflict exists.

Issues to analyze (read each full file before reasoning):

[For each issue in the batch:]
- **File**: [path]
- **ID**: [ISSUE-ID]
- **Type**: [BUG/FEAT/ENH/EPIC]
- **Priority**: [P0-P5]
- **Title**: [title]
- **Summary excerpt**: [first 300 chars of summary]

Return a structured list of conflicts found. For each conflict:

- conflict_type: requirement | objective | architecture | scope
- severity: high | medium | low
  - high: directly contradictory, will cause implementation failures if both proceed
  - medium: significant overlap or incompatibility requiring coordination
  - low: minor duplication or loose coupling concern
- issues: [LIST of affected ISSUE-IDs, e.g. ["FEAT-100", "FEAT-200"]]
- description: [1-2 sentence explanation of the specific conflict]
- recommendation: merge | deprecate | split | add_dependency | update_scope
  - merge: consolidate both into one issue (one closes, scope absorbed)
  - deprecate: one issue is superseded, should be closed
  - split: issues should be explicitly scoped to avoid overlap
  - add_dependency: issues can coexist but need blocked_by ordering
  - update_scope: scope notes should be added to clarify boundaries
- proposed_change: [specific action, e.g., "Close FEAT-200, add its auth-caching scope to FEAT-100"]

If no conflicts exist among this batch, return: []
```

Wait for **all batch agents** to complete before proceeding.

Handle agent failures: if a batch agent fails, retry once. If retry fails, log a warning for those issues and continue.

---

## Phase 2b: Cross-Theme Fingerprint Sweep (`--cross-theme` only)

**Skip this phase unless `CROSS_THEME = true` (`--cross-theme` flag).**

After Phase 2's intra-batch pass, run a fast non-LLM overlap check across all issue pairs — including pairs that span batch boundaries — and dispatch targeted single-pair agents for any cross-batch pair with file overlap.

### Step 1: Extract Fingerprints

For each issue file collected in Phase 1, extract its structured fingerprint:

```bash
ll-issues fingerprint <issue-path>
```

This outputs JSON: `{"id": "...", "files_to_modify": [...], "key_terms": [...]}`. Collect all fingerprints.

### Step 2: Identify Cross-Batch Overlap Pairs

For every pair `(A, B)` where A and B were in **different Phase 2 batches**, check:

- **File overlap** (primary signal): `|A.files_to_modify ∩ B.files_to_modify| ≥ 2`
  OR Jaccard `|A.files_to_modify ∩ B.files_to_modify| / |A.files_to_modify ∪ B.files_to_modify| ≥ 0.25`
- **Key-term fallback**: if either issue has no `files_to_modify` entries, apply when Jaccard of `key_terms` ≥ 0.15

Skip pairs already evaluated in Phase 2. Cap at **30 additional pairs** to bound token cost (≤30% overhead for ≤100 base issues in batches of 3–5).

### Step 3: Dispatch Pair Agents

For each pair above threshold, spawn one Task agent using the same conflict-detection prompt template as Phase 2, but with exactly those two issues as the batch. Spawn all cross-theme pair agents in a **single message** (parallel).

Handle agent failures: if a pair agent fails, log a warning and skip that pair.

### Step 4: Merge Cross-Theme Findings

Collect all cross-theme conflict records. These feed into Phase 3's deduplication step without special handling — Phase 3 merges by `issues` pair membership regardless of whether the finding came from a Phase 2 batch or a Phase 2b pair agent.

**Cost note**: Phase 2b dispatches one agent per overlapping cross-batch pair. For 50 issues in 10 batches of 5, expect ≤10 additional agents (≤20% overhead). The 30-pair cap bounds worst-case cost.

---

## Phase 3: Synthesize Report

Aggregate all batch findings:

1. **Deduplicate**: merge any identical conflict pairs reported by overlapping batches
2. **Group by severity**: high → medium → low
3. **Within each severity group**: sort by issue priority (P0 first)

If no conflicts were found across all batches:

```
================================================================================
AUDIT ISSUE CONFLICTS
================================================================================

No conflicts detected among [N] active issues.

All issues appear to have compatible requirements, objectives, architecture
decisions, and scope boundaries.
================================================================================
```

Output this message and stop (exit 0).

Otherwise, display the conflict report:

```
================================================================================
AUDIT ISSUE CONFLICTS
================================================================================

Issues scanned: [N]
Conflicts found: [C] ([H] high / [M] medium / [L] low)

## HIGH SEVERITY

| # | Type | Issues | Description | Recommendation |
|---|------|--------|-------------|----------------|
| 1 | [type] | [ID-A] vs [ID-B] | [description] | [recommendation] |

## MEDIUM SEVERITY

| # | Type | Issues | Description | Recommendation |
|---|------|--------|-------------|----------------|
| 2 | [type] | [ID-A] vs [ID-B] | [description] | [recommendation] |

## LOW SEVERITY

| # | Type | Issues | Description | Recommendation |
|---|------|--------|-------------|----------------|
| 3 | [type] | [ID-A] vs [ID-B] | [description] | [recommendation] |

================================================================================
```

---

## Phase 4: Apply Recommendations

### Dry-Run Mode (`--dry-run`)

Output the report (Phase 3) and stop. Do not modify any issue files.

```
Dry-run mode: no changes applied.
```

### Auto Mode (`--auto`)

Apply **all** recommendations without prompting. For each conflict, execute the appropriate action (see Phase 4b below).

### Interactive Mode (default)

For each conflict, present an `AskUserQuestion` prompt with options shaped by recommendation type.

**merge / deprecate** conflicts:

```yaml
questions:
  - question: "[SEVERITY] conflict: [ISSUE-A] vs [ISSUE-B] — [description]. Apply recommendation?"
    header: "[ISSUE-A] vs [ISSUE-B]"
    multiSelect: false
    options:
      - label: "Yes, apply — [proposed_change summary]"
        description: "[specific action, e.g., merge scope into ISSUE-A, close ISSUE-B]"
      - label: "No, keep both as-is"
        description: "Leave both issues unchanged"
      - label: "Add dependency instead"
        description: "Add blocked_by frontmatter to link them without closing either"
```

**add_dependency** conflicts:

```yaml
questions:
  - question: "Add dependency link: [ISSUE-A] should depend on [ISSUE-B]. Which field?"
    header: "[ISSUE-A]"
    multiSelect: false
    options:
      - label: "blocked_by (hard stop)"
        description: "Appends blocked_by: [ISSUE-B] to [ISSUE-A] frontmatter — ISSUE-B must complete before ISSUE-A can start (wave-gated)"
      - label: "depends_on (soft ordering)"
        description: "Appends depends_on: [ISSUE-B] to [ISSUE-A] frontmatter — preferred when ordering is desirable but not strictly required"
      - label: "No, skip"
        description: "Leave both issues unchanged"
```

**split / update_scope** conflicts:

```yaml
questions:
  - question: "Scope overlap: [ISSUE-A] vs [ISSUE-B] — [description]. Add scope note?"
    header: "[ISSUE-A] vs [ISSUE-B]"
    multiSelect: false
    options:
      - label: "Yes, append scope clarification note"
        description: "Adds a ## Scope Boundary note to each issue clarifying their split"
      - label: "No, keep as-is"
        description: "Leave both issues unchanged"
```

---

## Phase 4b: Execute Approved Changes

Track every modified file path so Phase 5 stages only audit-touched files:

```bash
MODIFIED_FILES=()
```

For each approved recommendation:

### merge / deprecate

1. Identify the issue to be **kept** and the one to be **closed/superseded**
2. If merging scope: before appending, read the kept issue file and check whether `## Scope Addition` already contains a reference to `[CLOSED-ID]`. If found, skip the append and log `[idempotent: Scope Addition for CLOSED-ID already present]`. Otherwise, append a `## Scope Addition` note to the kept issue file:

```markdown

---

## Scope Addition

**Source**: Merged from [CLOSED-ID] during `/ll:audit-issue-conflicts` conflict resolution.

[Relevant scope absorbed from CLOSED-ID]
```

3. Add a resolution section to the closed issue file: before appending, check whether `## Resolution` is already present in the closed issue file. If found, skip and log `[idempotent: Resolution already present]`. Otherwise, append:

```markdown

---

## Resolution

- **Status**: Closed - Superseded
- **Completed**: YYYY-MM-DD
- **Reason**: Superseded by [KEPT-ID] via conflict resolution audit
- **Proposed change**: [proposed_change from conflict record]
```

4. Update the closed issue's frontmatter `status: done` using the Edit tool.

5. Track both modified files:

```bash
MODIFIED_FILES+=("[kept-issue-path]" "[closed-issue-path]")
```

6. Append session log to closed issue:

```bash
ll-issues append-log "[issue-file-path]" /ll:audit-issue-conflicts
```

7. Append session log to kept issue:

```bash
ll-issues append-log "[kept-issue-path]" /ll:audit-issue-conflicts
```

### add_dependency

Append either `blocked_by: [ISSUE-B]` (hard stop — must complete first) or `depends_on: [ISSUE-B]` (soft ordering — preferred when no hard dependency exists) to the frontmatter of the dependent issue file using Edit, according to the user's choice from the interactive prompt. Track the modified file:

```bash
MODIFIED_FILES+=("[issue-path]")
```

Then append session log:

```bash
ll-issues append-log "[issue-path]" /ll:audit-issue-conflicts
```

### split / update_scope

Before appending to each affected issue, check whether `## Scope Boundary` is already present in that file and already references `[OTHER-ID]`. If found, skip the append and log `[idempotent: Scope Boundary for OTHER-ID already present]`. Otherwise, append a scope boundary note:

```markdown

---

## Scope Boundary

**Note** (added by `/ll:audit-issue-conflicts`): [Specific scope clarification. E.g., "This issue covers X only. Related issue [OTHER-ID] covers Y."]
```

Then track each modified file and append session log:

```bash
MODIFIED_FILES+=("[issue-path]")
ll-issues append-log "[issue-path]" /ll:audit-issue-conflicts
```

---

## Phase 5: Cleanup

Stage only files that were modified during Phase 4b — never stage untracked files the audit did not touch:

```bash
for f in "${MODIFIED_FILES[@]}"; do
    git add "$f"
done
```

---

## Phase 6: Final Report

```
================================================================================
AUDIT ISSUE CONFLICTS — COMPLETE
================================================================================

## SUMMARY
- Issues scanned: [N]
- Conflicts found: [C]
- Recommendations applied: [A]
- Skipped (idempotent): [I]
- Skipped (user declined or no-op): [S]
- Could not evaluate: [W]

## APPLIED CHANGES
- [ISSUE-A] vs [ISSUE-B]: [action taken, e.g., "FEAT-200 closed, scope merged into FEAT-100"]
- [ISSUE-A]: [action taken, e.g., "blocked_by: FEAT-300 added to frontmatter"]

## SKIPPED (IDEMPOTENT)
- [ISSUE-A] vs [ISSUE-B]: Scope Boundary for OTHER-ID already present — no duplicate appended

## UNCHANGED
- [ISSUE-A] vs [ISSUE-B]: user declined recommendation
- [ISSUE-A] vs [ISSUE-B]: no action needed (low severity, skipped in auto mode)

## SKIPPED (evaluation errors)
- [file]: Could not evaluate (subagent failure)

## GIT STATUS
All changes staged in {{config.issues.base_dir}}/

================================================================================
```

---

## Examples

```bash
# Interactive mode: review each conflict and approve/reject
/ll:audit-issue-conflicts

# Auto-apply all recommendations without prompting
/ll:audit-issue-conflicts --auto

# Report only, no changes
/ll:audit-issue-conflicts --dry-run

# Cross-theme sweep: detect conflicts across thematic boundaries
/ll:audit-issue-conflicts --cross-theme

# Cross-theme dry-run: report only, no changes
/ll:audit-issue-conflicts --dry-run --cross-theme
```

## Related Commands

- `/ll:tradeoff-review-issues` — Evaluates utility vs complexity (is it worth doing?)
- `/ll:align-issues` — Validates issues against project goals
- `/ll:map-dependencies` — Traces blocked_by relationships
- `/ll:refine-issue` — Fills knowledge gaps in a single issue