Repository Analyser

Discovers how a repository works — its architecture, patterns, conventions, and dependencies. The goal is to understand "how things are done here" so agents can follow existing practices.

Note: This skill is primarily used via the Repo Analyser agent as a subagent. The content here serves as reference documentation.

Philosophy

Discover, don't assume. Every repository has its own conventions. Rather than looking for specific frameworks, observe what patterns actually exist and document them. If something is unclear, note it as "unclear" rather than guessing.

When to Run

•First time working in a repository
•When .planning/CONVENTIONS.md doesn't exist
•When explicitly asked to refresh conventions

Cross-Platform Commands

Use your search and read tools for all codebase exploration. Only use the terminal for dotnet and git commands — these work identically across all shells.

Discovery Process

The Repo Analyser agent contains detailed discovery instructions. In summary, explore these areas:

•Solution Overview — find *.sln and *.csproj files, note .NET version(s) and project types
•Architecture Pattern — identify folder structure signals (Vertical Slice, Clean Architecture, Hexagonal, N-Tier, or mixed)
•External Dependencies — scan PackageReference entries and config files for databases, message brokers, cloud services
•Testing Approach — examine test projects, naming conventions, assertion libraries, mocking frameworks (read 3-5 actual test files)
•Code Patterns — identify request handling, validation, error handling, mapping, and DI approaches (read 3-5 representative files)
•Code Style — nullable refs, namespace style, primary constructors, record types, naming conventions
•Anything Else Notable — custom base classes, domain-specific patterns, unusual structures

Output Format

Create .planning/CONVENTIONS.md using this template:

markdown

# Repository Conventions

> Generated by repo-analyser on {date}
> Review and adjust if needed. Re-run if conventions change significantly.

## Overview

| Aspect | Value |
|--------|-------|
| Solution | {name} |
| .NET Version | {version} |
| Architecture | {pattern or "unclear"} |
| Test Framework | {framework} |
| Key Packages | {e.g., FluentValidation 11.x, MediatR 12.x} |

## Architecture

{Description of the architectural pattern observed, with folder structure examples}

## Project Structure

{Folder tree with purpose annotations}

## External Dependencies

| Type | Technology | Notes |
|------|------------|-------|
| Database | {e.g., SQL Server via EF Core} | {any notes} |
| Messaging | {e.g., Azure Service Bus} | {any notes} |

## Testing Conventions

| Aspect | Convention |
|--------|------------|
| Framework | {xUnit/NUnit/MSTest} |
| Assertions | {FluentAssertions/Shouldly/built-in} |
| Mocking | {Moq/NSubstitute/none} |
| Test naming | {pattern} |
| Organisation | {description} |

### Example Test

{Actual test method from codebase showing naming and structure}

## Code Patterns

| Aspect | Pattern |
|--------|---------|
| Request handling | {MediatR/custom handlers/direct/etc.} |
| Validation | {FluentValidation/DataAnnotations/manual} |
| Error handling | {Result type/exceptions/etc.} |
| Mapping | {AutoMapper/Mapster/manual/extensions} |
| API style | {Controllers / Minimal APIs / mixed} |
| Data access | {Dapper raw / Dapper.Contrib / EF Core / mixed} |

### Example Handler/Service

{Simplified example from codebase showing typical structure}

### Example Error Handling

{Actual example showing Result<T> vs exception usage}

## Code Style

| Aspect | Convention |
|--------|------------|
| Nullable refs | {enabled/disabled} |
| Namespaces | {file-scoped/block-scoped} |
| Records | {used for X/not used} |
| Field naming | {_camelCase/other} |

## Notes

{Anything unusual, unclear, or worth highlighting}

---

## For Agents

**Critical rules when writing code in this repository:**

1. **Architecture:** Place new features in `{path pattern}` following {pattern}
2. **Error handling:** Use `{Result<T> | exceptions}` — see Example Error Handling above
3. **Test naming:** `{pattern}` — see Example Test above
4. **Assertions:** Use `{assertion library}` syntax
5. **New files:** Follow the folder structure in Project Structure above
6. **API style:** Use `{Controllers | Minimal APIs}` — see existing endpoints for reference
7. **Data access:** Use `{Dapper pattern}` — see existing repositories/queries for reference

After Generation

•Briefly summarise what was discovered
•Highlight anything ambiguous that might need human clarification
•The file is ready for agents to reference