Skip to content
deferred-finding logo

Deferred Finding

deferred-finding

Use when a review finding cannot be fixed in current PR - creates properly documented tracking issue with full context, linked to parent, following full issue-driven-development process

SKILL.md

Full skill instructions

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:

Valid ReasonExample
Out of scopeFinding requires architectural change beyond PR scope
External dependencyRequires infrastructure/​config change
Breaking changeWould require major version bump
Separate concernLogically independent from current work

Never Defer Without Tracking

Invalid ApproachReality
"We'll fix it later"Without tracking, later never comes
"It's minor"Minor issues compound into major problems
"Not my problem"You found it, you track it
"Good enough"Good enough creates technical debt

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]

ReasonDetails
Category[out-of-scope / external-dependency / breaking-change / separate-concern]
Justification[Specific explanation]

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

```bash
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)

| # | Severity | Finding | Tracking Issue | Justification |
|---|----------|---------|----------------|---------------|
| 1 | HIGH | Rate limiting needed | #456 | Requires infrastructure changes |

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.

| Property | Value |
|----------|-------|
| Blocked At | Step 9 (Code Review) |
| Dependencies | #456 |
| Reason | Critical deferred finding blocks PR |

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

DepthMeaning
1Finding from original issue's review
2Finding 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:

LabelPurpose
review-findingIdentifies as born from review
spawned-from:#NLinks to parent issue
depth:NTracks 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

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View