Deferred Finding

Overview

Process for creating tracking issues when review findings cannot be addressed in the current PR.

Core principle: No finding disappears. Every deferral is tracked.

ABSOLUTE REQUIREMENT: Deferred findings MUST have tracking issues. There is no other option.

When to Defer

A finding may ONLY be deferred when:

Never Defer Without Tracking

Deferral Process

Step 1: Verify Deferral is Appropriate

Ask yourself:

• Can this reasonably be fixed in this PR? If yes, FIX IT.
• Is there a valid reason from the "When to Defer" table?
• Have you tried to fix it first?

Step 2: Determine Finding Details

Document:

• What is the finding?
• Why is it a problem?
• Where in the code?
• What's the severity?
• Why can't it be fixed now?

Step 3: Create Tracking Issue

Use this template:

## [Finding] [Brief description] (from #[PARENT])

### Origin

This issue was created during code review of #[PARENT_ISSUE].

| Property | Value |
|----------|-------|
| Parent Issue | #[PARENT_ISSUE] |
| Parent PR | #[PARENT_PR] (if exists) |
| Finding ID | F-[PARENT]-[N] |
| Severity | [CRITICAL/HIGH/MEDIUM/LOW] |
| Review Criterion | [Which of 7 criteria OR OWASP category] |
| Depth | [N] |

### Finding Details

**What was found:**
[Detailed description of the issue - be specific]

**Location:**
- File: `[path/to/file.ts]`
- Line(s): [N-M]
- Function: `[functionName()]`

**Why it matters:**
[Impact if not addressed - be concrete]

**Evidence:**
```[language]
[Code snippet showing the issue]

Why Deferred

[Explain why this cannot be fixed in the parent PR]

Acceptance Criteria

• [Specific criterion 1 - must be verifiable]
• [Specific criterion 2]
• [How to verify the fix]

Links

• Parent Issue: #[PARENT_ISSUE]
• Review Comment: [Link to review artifact if applicable]

Labels: review-finding, spawned-from:#[PARENT], depth:[N], [severity]

This issue follows the full issue-driven-development process including its own code review.

### Step 4: Create Issue via CLI

gh issue create \ --title "[Finding] Rate limiting needed on auth endpoint (from #123)" \ --body "$(cat <<'EOF' [Full template body here] EOF )" \ --label "review-finding" \ --label "depth:1" \ --label "high"

Note: Create the `spawned-from:#N` label if it doesn't exist:

gh label create "spawned-from:#123" --color "C2E0C6" --description "Spawned from issue #123" 2>/dev/null || true gh issue edit [NEW_ISSUE] --add-label "spawned-from:#123"

### Step 5: Update Review Artifact

Add the new issue to the "Findings Deferred" section:

Findings Deferred (With Tracking Issues)

### Step 6: Update Parent Issue (If Deviation Required)

If the deferred finding BLOCKS the parent PR (e.g., critical security issue):

Add awaiting label

gh issue edit 123 --add-label "status:awaiting-dependencies"

Post deviation comment

gh issue comment 123 --body "$(cat <<'EOF'

Deviation: Awaiting Dependencies

This issue cannot proceed until deferred findings are resolved.

Work will resume when #456 is complete. EOF )"

## Tracking Issue Lifecycle

Once created, the tracking issue:

1. **Is a first-class issue** - Full issue-driven-development process
2. **Gets its own review** - Cannot skip comprehensive-review
3. **May create its own deferrals** - Depth increments
4. **Closes independently** - Does not auto-close with parent

## Depth Tracking

| Depth | Meaning |
|-------|---------|
| 1 | Finding from original issue's review |
| 2 | Finding from a depth-1 issue's review |
| 3+ | Deeper nesting - flag for human attention |

At depth 3+:

Deep Finding Chain Detected

This issue is at depth [N]. Chain:

• #100 (original)

- #101 (depth 1) - #102 (depth 2) - #103 (depth 3) - Current

Consider: Is there a systemic issue requiring broader attention?

## Labels

Required labels for tracking issues:

| Label | Purpose |
|-------|---------|
| `review-finding` | Identifies as born from review |
| `spawned-from:#N` | Links to parent issue |
| `depth:N` | Tracks nesting level |
| `[severity]` | critical/high/medium/low |

Optional labels:
- `security` - Security-related finding
- `status:pending` - Ready for work

## Checklist

Before marking finding as deferred:

- [ ] Verified cannot fix in current PR
- [ ] Valid deferral reason documented
- [ ] Tracking issue created with full template
- [ ] Issue has all required labels
- [ ] Issue linked to parent
- [ ] Review artifact updated with tracking issue number
- [ ] Parent issue updated (if deviation required)

## Integration

This skill is called by:
- `apply-all-findings` - When finding cannot be fixed
- `comprehensive-review` - When documenting deferrals

This skill creates:
- New GitHub issues following full `issue-driven-development` process
- Deviation state on parent issue (if blocking)

This skill references:
- `issue-lifecycle` - Issue management
- `issue-driven-development` - Process for new issues