1---2name: porcami-ai-dotfiles-conventional-comments3description: Conventional Comments4---56# Conventional Comments78Format for structured, actionable PR review comments. Based on [conventionalcomments.org](https://conventionalcomments.org/).910## Format1112```13<label> [decorations]: <subject>1415[discussion]16```1718## Labels1920| Label | Meaning | When to Use |21|-------|---------|-------------|22| `praise` | Highlights good work | Patterns done well, clever solutions, good test coverage |23| `nitpick` | Trivial preference-based suggestion | Naming style, formatting, minor readability — never blocking |24| `suggestion` | Proposes an improvement | Better approach, refactoring opportunity, pattern alignment |25| `issue` | Identifies a problem that must be addressed | Bugs, security flaws, data integrity risks, broken logic |26| `todo` | Small necessary change | Missing null check, absent test, required cleanup |27| `question` | Asks for clarification | Unclear intent, ambiguous logic, missing context |28| `thought` | Shares an idea for consideration | Alternative approaches, future considerations — not actionable now |29| `chore` | Mechanical task needed | Update a config, rename for consistency, remove dead code |30| `note` | Informational context | External dependency flags, environment requirements, FYI items |3132## Banking Domain Decorations3334| Decoration | Meaning |35|------------|---------|36| `(security)` | Security concern — injection, auth, data exposure |37| `(banking)` | Banking domain concern — idempotency, audit, financial rules |38| `(financial-integrity)` | Financial calculation or data correctness |39| `(audit)` | Audit trail or traceability concern |40| `(pii)` | Personally identifiable information exposure |41| `(performance)` | Performance concern — LINQ traps, N+1, boxing |42| `(test)` | Test quality or coverage concern |4344## Severity Mapping4546| Severity (code-reviewing) | Label | Decoration | Rationale |47|---------------------------|-------|------------|-----------|48| **Critical** | `issue` | `(blocking)` | Must fix before merge |49| **Important** | `suggestion` or `todo` | varies | `todo` for specific fixes; `suggestion` for approach changes |50| **Suggestion** | `suggestion` or `nitpick` | `(non-blocking)` | `nitpick` for pure style; `suggestion` for meaningful improvements |51| **External** | `note` | `(blocking)` | Requires human verification — always blocking |5253Security issues are always: `issue (blocking, security): <subject>`5455## Anti-Patterns5657| Don't | Do Instead |58|-------|------------|59| Mark style issues as `(blocking)` | Use `nitpick (non-blocking)` for style |60| Write a label with no discussion | Always include at least one sentence explaining *why* |61| Use `issue` for suggestions | Reserve `issue` for actual bugs or risks; use `suggestion` for improvements |62| Skip `praise` entirely | Include at least one `praise` per review |63| Omit decoration on `issue` | Every `issue` must have `(blocking)` — if it's not blocking, it's a `suggestion` |64| Use `todo` for large changes | Use `suggestion` for changes requiring design decisions; `todo` is for small fixes |65| Combine unrelated concerns | One comment per concern — split multi-issue comments |6667## Output Structure68691. **Summary header** — branch, commit count, files changed, build/test status, overall verdict702. **Per-file sections** — group comments by file path, each in a fenced code block713. **General section** — cross-cutting concerns that span multiple files724. **How to Use** — brief instructions for copying comments into Azure DevOps7374---75> Converted and distributed by [TomeVault](https://tomevault.io/claim/porcami) — claim your Tome and manage your conversions.76<!-- tomevault:4.0:skill_md:2026-04-14 -->
tomevault-io