Concerns Skill

---
name: concerns-skill
description: Framework for surfacing and tracking tech debt, known bugs, and security gaps in software codebases.
hints:
  - Check existing project docs for tech debt registers and known bugs if available.
  - Formulate codebase concern reports with specific file paths, line numbers, and factual impact.
  - Avoid emotional adjectives; use precise engineering terms (e.g. N+1 queries, race conditions).
  - Provide a clear, actionable fix or mitigation approach for every logged concern.
  - Update or remove concern entries immediately upon resolution.
---

# Codebase Concerns Skill

## Overview

This skill governs how known risks, tech debt, and codebase health issues are surfaced and maintained. Load this before making changes to high-risk areas, during phase planning, or when onboarding a new agent context.

## Workflow

- **[CONCERN-001] Always Check Before Changing**
  - Before modifying a flagged area, read its concern entry to understand risk, workarounds, and safe modification paths.
  - If no concern entry exists for an area you're about to change, check for fragility signals (complex chains, missing tests, shared mutable state).

- **[CONCERN-002] Concern Entry Format**
  - Every concern must include: area/component, issue description, why it exists, impact, and fix approach.
  - Always include **file paths** — concerns without locations are not actionable.
  - Use specific measurements for performance issues (`500ms p95`, not "slow").
  - Include reproduction steps for bugs.

- **[CONCERN-003] Categories**
  - **Tech Debt**: Shortcuts with known impact and a fix path.
  - **Known Bugs**: Reproducible defects with symptoms, trigger, and workaround.
  - **Security Considerations**: Risks with current mitigation and recommendations.
  - **Performance Bottlenecks**: Measured slow paths with root cause and improvement plan.
  - **Fragile Areas**: Components that break easily — document safe modification steps.
  - **Scaling Limits**: Capacity numbers and what happens at the limit.
  - **Dependencies at Risk**: Deprecated, unmaintained, or breaking-change packages.
  - **Test Coverage Gaps**: Untested paths and the risk they carry.

- **[CONCERN-004] Tone & Accuracy**
  - Professional, not emotional (`"N+1 query pattern"` not `"terrible queries"`)
  - Solution-oriented — always suggest a fix approach, not just a problem
  - Factual — use real numbers, not vague qualifiers
  - No opinions without evidence; no complaints without solutions

- **[CONCERN-005] Maintenance**
  - Mark concerns as resolved when the underlying issue is fixed.
  - Add new concerns as they are discovered — during audits, debugging, or code review.
  - Include the analysis date on each update.
  - This is a living document, not a complaint list.

## When to Load This Skill

| Scenario | Action |
|---|---|
| About to change auth, middleware, or DB layer | Read **Fragile Areas** and **Security Considerations** |
| Planning a new feature phase | Read **Tech Debt** and **Scaling Limits** |
| Debugging an unexpected failure | Read **Known Bugs** |
| Writing or reviewing tests | Read **Test Coverage Gaps** |
| Evaluating dependencies | Read **Dependencies at Risk** |

## Required Checks

- [ ] Concern entry has a file path — no location-less concerns.
- [ ] Performance numbers are actual measurements, not estimates.
- [ ] Bugs include a reproduction trigger.
- [ ] Resolved concerns are removed or marked fixed with a date.
- [ ] New concerns added after any audit or incident.

## When to Use
- Use when preparing to work on existing codebases, planning refactoring phases, or onboarding onto unfamiliar directories.
- NOT for styling changes or single-file variable renames unless they are part of a larger architectural risk.

## Common Rationalizations
| Rationalization | Reality |
|---|---|
| I don't have time to catalog debt. | Logging debt takes 2 minutes and prevents the next developer from breaking the system. |
| It's just a temporary hack, no need to log it. | Temporary hacks frequently become permanent; documenting them prevents future blindspots. |

## Red Flags
- Technical debt or security gaps left unrecorded in codebase documentation.
- Vague reports like "the DB is slow" without specific query profiles, execution times, or metric traces.
- Modifying fragile codebase components without checking existing concern registers or tech debt lists first.

## Verification
After completing the skill, confirm:
- [ ] All newly identified concerns are logged with precise file paths, triggers, and suggested fix paths.
- [ ] Any resolved concerns are updated in the tracking documents.
- [ ] Tone of logged issues is kept entirely factual, metric-driven, and constructive.