devflow:foundation:audit-conventions

Audit Conventions

Say exactly: "SKILL INVOKED: audit-conventions"

Read-only comparison of a repository's actual state against the team's captured conventions. Shows deltas — what the team says vs what the repo does. Nothing more.

Critical Rules

• Read-only. Do not create, modify, or delete any files in the repo. Ever.
• Report deltas, not judgments. "Team says X, repo does Y." Not "repo should do X."
• No suggestions. Do not recommend fixes, alignment, or changes. Just report what is.
• Every section gets compared. Don't skip convention sections because they seem irrelevant.
• If conventions don't exist, stop. This skill requires team conventions to audit against.

---

Step 1: Detect Tech Stack & Find Matching Conventions

1. Detect the repo's tech stack using ../references/tech-stack-detection.md:

• Check for framework files (composer.json, package.json, pom.xml, etc.)
• Identify primary stack (e.g., "php-laravel", "python-fastapi", "react-typescript")
• Store detected stack for reporting

2. Load DevFlow config:

• Read ~/.claude/plugins/config/devflow/config.md
• If no config → tell user: "No DevFlow configuration found. Run /devflow-setup first." STOP.

3. Search for stack-specific conventions:

Search backends in this order (stop at first match):

Priority 1: Stack-specific conventions

If RAG Memory enabled:

• mcp__rag-memory-primary__search_documents(query="{detected stack} conventions") (e.g., "PHP Laravel conventions")
• If found → load and confirm with user

If Confluence enabled:

• mcp__atlassian__searchConfluenceUsingCql(cql="title ~ '{detected stack} conventions'")
• If found → load and confirm with user

If Google Drive enabled:

• search_files(query="{detected stack} conventions")
• If found → load and confirm with user

Priority 2: Broader conventions (if stack-specific not found)

Try language-level:

• Search for "{language} conventions" (e.g., "PHP conventions" if Laravel-specific not found)

Priority 3: Generic conventions (if nothing stack-specific found)

Search broadly:

• "team conventions", "coding standards", "workflow"

Priority 4: Repo-local conventions

Check the repo itself:

• .claude/rules/team-conventions.md — portable conventions file

If nothing found in any location:

"No team conventions found for {detected stack}. Run /devflow:foundation:capture-conventions to capture conventions for this tech stack first." STOP.

If found: Show what was found and confirm before proceeding.

"Found: {convention document title} (matches {detected stack})"

---

Step 2: Analyze the Repository

Examine the repo's actual state across all convention areas:

• Package files (package.json, pyproject.toml, Cargo.toml, go.mod) → detect stack, dependencies, scripts
• Config files (.eslintrc, tsconfig, prettier, .editorconfig, biome.json) → detect formatter, linter, type settings
• Test files → detect test framework, file location, patterns, coverage config
• CI/CD config (.github/workflows, .gitlab-ci.yml, Jenkinsfile) → detect CI requirements, merge strategy
• Directory structure → detect architecture patterns, monorepo vs single repo
• Documentation → detect what docs exist (README, API docs, ADRs, changelog, runbooks)
• Git history → detect branching patterns, commit message format, branch naming
• Security config → detect dependency scanning, static analysis tools, secrets management

Be thorough. Look at every area the conventions document covers.

---

Step 3: Generate Delta Report

Compare each section of the team conventions against the repo's actual state.

For each convention item, classify as one of:

• Aligned — convention matches repo reality
• Deviation — repo does something different from convention
• Not observable — can't determine from repo analysis alone
• Not applicable — convention doesn't apply to this repo's stack

Report Format

Present a structured report:

# Convention Audit: {repo name}
Date: {YYYY-MM-DD}
Detected tech stack: {detected stack}
Conventions source: {where conventions were loaded from}

## Summary
- Aligned: {count}
- Deviations: {count}
- Not observable: {count}
- Not applicable: {count}

## Tech Stack
| Convention | Team Says | Repo Has | Status |
|-----------|-----------|----------|--------|
| Language | TypeScript | TypeScript | Aligned |
| Framework | Next.js | Express | Deviation |

## Coding Standards
| Convention | Team Says | Repo Has | Status |
|-----------|-----------|----------|--------|
| Formatter | Prettier | Prettier (.prettierrc found) | Aligned |
| Linter | ESLint strict | No ESLint config found | Deviation |

## Testing
...

## Documentation Standards
...

## Git & Workflow
...

## Architecture
...

## Security Practices
...

## Definition of Done
...

## Preferred Libraries
...

---

Step 4: Present Results

Present the full report to the developer.

"Here's your convention audit. This is a read-only comparison — no changes have been made to your repo."

Do NOT:

• Suggest fixing deviations
• Offer to update files
• Recommend aligning with conventions
• Create any documents or files
• Editorialize about whether deviations are good or bad

The developer now has a clear picture of where their repo aligns with and deviates from team conventions. What they do with that information is entirely up to them.

---

⛔ STOP

Skill complete.