scan-conventions

name	scan-conventions
description	Scans a real codebase and writes coding-conventions.md from what it actually finds — variable style, SQL patterns, error handling, INSERT strategy, naming. Run once on any new project to bootstrap the convention system. Triggers on "scan conventions", "generate conventions", "bootstrap conventions", "extract conventions from code", "what are the conventions".
allowed-tools	Glob, Grep, Read, Write

Skill: scan-conventions

Reads real code from the target codebase and extracts the actual conventions in use. Writes coding-conventions.md from evidence, not assumptions.

---

Step 1 — Locate the codebase

Look for:

• Primary language files (Java/JS/Python/TS — whatever the project uses)
• Main entry point or router file
• A utility/helper file with 5+ methods

If unclear, ask the user: "Where are the main source files? Any primary utility class I should read?"

---

Step 2 — Sample 3-5 real methods

Read actual methods. Look for:

Variable declarations:

• Declared at top of method or inline?
• Declared then assigned, or declaration + assignment combined?

SQL / DB patterns (if applicable):

• SQL assigned to a variable before passing to a query method?
• Parameterized queries? String concatenation? ORM?
• Specific quoting helpers (e.g. fmtCondition, fAddQuotes)?

Error handling:

• What does a failure return? "Error: ..." string? Exception? null?
• Specific error-check helpers (e.g. UFmt.containsError)?

Naming:

• camelCase, snake_case, PascalCase?
• Variable names include type prefix or drop it?

Control flow:

• Braces on every if/else, or omitted for single-statement bodies?
• Ternary operators used or avoided?
• Early returns or single-exit?

String comparison (Java/JS):

• var.equalsIgnoreCase("value") or "value".equalsIgnoreCase(var)?

---

Step 3 — Sample JS/frontend (if applicable)

• var vs let/const?
• Arrow functions vs function() {}?
• Template literals vs concatenation?
• DOM: getElementById vs querySelector vs $('#id')?
• Named params object before API call vs inline?

---

Step 4 — Identify INSERT strategy (if DB-heavy)

Grep for INSERT statements. Do any tables use auto-increment/IDENTITY? List them — they may need special handling (e.g. no explicit ID in INSERT).

---

Step 5 — Write coding-conventions.md

Write to coding-conventions.md in the project memory or root:

# Coding Conventions — [Project Name]
> Generated by /scan-conventions on [date].
> Based on [N] methods sampled from [files]. Review and correct anything that looks wrong.

## [Language] Conventions

### Variable Declarations
[finding]

### Error Handling
[finding]

### SQL / DB Pattern
[finding — or "N/A"]

### INSERT Strategy
[finding — list IDENTITY tables if found]

### Naming
[finding]

### Control Flow
[finding]

### String Comparison
[finding]

## JavaScript / Frontend (if applicable)

### Syntax
[finding]

### DOM Access
[finding]

### API Calls
[finding]

## ⚠️ Ambiguous — needs manual confirmation
[anything found with mixed usage — e.g. "Found both var and let — which is standard?"]

---

Step 6 — Report

Tell the user:

• Files sampled
• Key patterns confirmed
• Anything ambiguous that needs manual review

Ask: "Does this match what you know? Anything to correct before I treat this as authoritative?"

---

Notes

• This is a starting point, not a finished document
• Ambiguous patterns must be flagged — never assumed
• After the first real coding session, run /learn to add project-specific nuances
• Run again after a major refactor to catch convention drift