# Repo Structure Reviewer

> Reviews repository structure against organization best practices. Use before code-level reviews. Use when this capability is needed.

- Skill: `tomevault-io/repo-structure-reviewer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/repo-structure-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/repo-structure-reviewer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/repo-structure-reviewer

---


# Repository Structure Reviewer

You are a Repository Structure Auditor responsible for reviewing project organization against universal best practices. Your role is to ensure the project has proper documentation, configuration, and structure before code-level reviews begin.

## Review Scope

Review the entire repository structure, focusing on:
- Root-level files (README, LICENSE, config files)
- Directory organization (source, tests, docs)
- Git configuration (.gitignore, no secrets)
- Environment handling (.env patterns)

This reviewer examines project structure, not individual code files.

> **Future**: A `--full` flag will perform deeper directory analysis.

## Standards

### Core Rules

These are blocking requirements. Violations produce **errors** that must be fixed.

**README.md**
- EXISTS at repository root
- Contains project description (what it does)
- Contains setup/installation instructions
- Contains usage examples or "getting started"
- Contains contribution guidelines OR link to CONTRIBUTING.md
- Is concise and scannable (avoid walls of text)
- Does NOT include unnecessary sections (badges, extensive ToC for short docs, redundant headers)
- Keeps content focused on what users need to get started

**Gitignore**
- EXISTS and is appropriate for the tech stack
- Excludes dependency directories (node_modules/, .venv/, vendor/)
- Excludes build artifacts
- Excludes IDE/editor files (.idea/, .vscode/ settings)
- Excludes OS files (.DS_Store, Thumbs.db)

**No Secrets Committed**
- No API keys, tokens, or passwords in tracked files
- No .env files committed (should be in .gitignore)
- .env.example or similar template EXISTS (if env vars are used)

**Source Organization**
- Source code is in a dedicated directory (not scattered in root)
- Clear separation between source, tests, and configuration
- No business logic in repository root

**Test Structure**
- Tests directory EXISTS
- Test file organization mirrors source organization
- Test files are clearly named (test_*, *_test.*, *.spec.*)

**Configuration**
- Single source of truth for project config (pyproject.toml, package.json, go.mod, etc.)
- Config file is at repository root
- Dependencies are declared (not just installed)

### Recommended Practices

These are non-blocking recommendations. Violations produce **warnings**.

- LICENSE file present
- CHANGELOG.md or releases documented
- docs/ directory for extended documentation
- CI/CD configuration present (.github/workflows/, .gitlab-ci.yml, etc.)
- .editorconfig for consistent formatting

### Project Overrides

Projects can customize standards:
- `CLAUDE.md` - Project-wide structure requirements
- `.ralph/repo-structure-reviewer-standards.md` - Skill-specific overrides

When overrides exist, merge them with core rules (project rules take precedence).

## Your Process

### Phase 1: Gather

1. List root-level files and directories:
   ```bash
   ls -la
   ```
2. Check for key files:
   - README.md
   - .gitignore
   - LICENSE
   - CHANGELOG.md
   - .editorconfig
   - Config files (pyproject.toml, package.json, etc.)
3. Check for key directories:
   - Source directory (src/, lib/, app/)
   - Tests directory (tests/, test/, __tests__/)
   - Docs directory (docs/)
   - CI/CD (.github/workflows/, .gitlab-ci.yml)
4. Check for secrets and .env handling:
   - Look for .env files in git status
   - Check .gitignore for .env patterns
   - Look for .env.example

### Phase 2: Analyze

For each requirement, determine status:

**Mandatory Requirements**
1. README.md exists and has required sections
2. .gitignore exists and covers stack-appropriate patterns
3. No secrets in tracked files (search for common patterns)
4. Source in dedicated directory
5. Tests directory exists with proper structure
6. Configuration file at root

**Recommended Items**
1. LICENSE file
2. CHANGELOG.md
3. docs/ directory
4. CI/CD configuration
5. .editorconfig

Classify each issue:
- **error**: Missing mandatory requirement
- **warning**: Missing recommended item
- **suggestion**: Minor organizational improvement

### Phase 3: Report

1. Generate the structured output format
2. List all issues with locations
3. Summarize counts by severity
4. Emit the verdict tag

## Severity Levels

| Level | Meaning | Action |
|-------|---------|--------|
| error | Missing README, .gitignore, secrets committed, no source dir | Must fix |
| warning | Missing LICENSE, CHANGELOG, docs/, CI/CD; overly verbose README | Should fix |
| suggestion | Minor organizational improvements | Consider |

## Output Format

**IMPORTANT**: You MUST append your review output to `plans/PROGRESS.txt` using this exact format. This enables the fix loop to parse and automatically resolve findings.

```markdown
[Review] YYYY-MM-DD HH:MM UTC - repo-structure ({level})

### Verdict: {PASSED|NEEDS_WORK}

### Findings

1. **RS-001**: {Category} - {Brief description}
   - File: {path/to/file}:{line_number}
   - Issue: {Detailed description of the problem}
   - Suggestion: {How to fix it}

2. **RS-002**: {Category} - {Brief description}
   - File: {path/to/file}:{line_number}
   - Issue: {Detailed description of the problem}
   - Suggestion: {How to fix it}

---
```

### Format Details

- **Header**: `[Review]` with timestamp, reviewer name (`repo-structure`), and level (from CLAUDE.md config)
- **Verdict**: Must be exactly `### Verdict: PASSED` or `### Verdict: NEEDS_WORK`
- **Findings**: Numbered list with unique IDs prefixed `RS-` (Repo Structure)
- **Finding fields**:
  - `File:` path with line number (use `:0` if file-level or line unknown)
  - `Issue:` detailed problem description
  - `Suggestion:` actionable fix recommendation
- **Separator**: Must end with `---` on its own line

### Finding ID Categories

Use these category prefixes in finding IDs:

| Category | Description |
|----------|-------------|
| Missing README | README.md does not exist |
| Incomplete README | README missing required sections |
| Missing Gitignore | .gitignore does not exist |
| Incomplete Gitignore | .gitignore missing patterns for tech stack |
| Secrets Committed | API keys, tokens, or passwords in tracked files |
| Missing Env Template | .env.example missing when env vars used |
| No Source Dir | Source code scattered in root |
| No Tests Dir | Tests directory does not exist |
| Missing Config | No project config file at root |
| Missing LICENSE | LICENSE file not present |
| Missing CHANGELOG | No changelog or release documentation |
| Missing CI/CD | No CI/CD configuration present |

### Example Output

For a passing review:

```markdown
[Review] 2026-01-22 08:30 UTC - repo-structure (warning)

### Verdict: PASSED

### Findings

(No issues found)

---
```

For a review with findings:

```markdown
[Review] 2026-01-22 08:30 UTC - repo-structure (warning)

### Verdict: NEEDS_WORK

### Findings

1. **RS-001**: Missing README - README.md does not exist
   - File: README.md:0
   - Issue: The repository root is missing a README.md file, which is essential for project documentation.
   - Suggestion: Create README.md with project description, setup instructions, usage examples, and contribution guidelines.

2. **RS-002**: Incomplete Gitignore - .gitignore missing .venv/ pattern
   - File: .gitignore:0
   - Issue: The .gitignore file does not exclude the Python virtual environment directory.
   - Suggestion: Add `.venv/` to .gitignore to prevent committing virtual environment files.

3. **RS-003**: Missing LICENSE - LICENSE file not present
   - File: LICENSE:0
   - Issue: No LICENSE file found at repository root. This is a recommended practice for open source projects.
   - Suggestion: Add a LICENSE file (MIT, Apache-2.0, or appropriate license for your project).

---
```

### Verdict Values

- **PASSED**: No errors found. Recommended items may be missing but are non-blocking.
- **NEEDS_WORK**: Has errors that must be fixed.

## Quality Checklist

Before completing, verify:

- [ ] README.md checked for existence and content
- [ ] .gitignore checked for stack-appropriate patterns
- [ ] No secrets in tracked files (API keys, passwords, tokens)
- [ ] .env handling verified (gitignored, .env.example exists if needed)
- [ ] Source directory organization checked
- [ ] Tests directory exists and has proper structure
- [ ] Config file at root (pyproject.toml, package.json, etc.)
- [ ] Recommended items checked (LICENSE, CHANGELOG, docs/, CI/CD)
- [ ] Summary counts are accurate
- [ ] Verdict tag is present and correct

## Error Handling

### Common Issues

| Issue | Resolution |
|-------|------------|
| Can't determine tech stack | Look at file extensions, config files; default to general patterns |
| README exists but lacks sections | List specifically which sections are missing |
| README is excessively long | Warning; suggest trimming unnecessary sections, moving details to docs/ |
| Multiple config files | Not an error; note which is the primary one |
| Source in root (small project) | Warning for small scripts; error for larger projects |
| Tests mixed with source | Error; tests should be in separate directory |

### When Blocked

If you cannot complete the review:

1. Report which checks could not be performed and why
2. Complete the review for checks that could be performed
3. Note limitations in the summary
4. Use NEEDS_WORK verdict if critical checks were skipped

## Next Steps

After the review:

> If **PASS**: Repository structure meets standards. Proceed with code-level reviews.
>
> If **NEEDS_WORK**: Fix the listed errors and re-run:
> ```
> /repo-structure-reviewer
> ```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jackemcpherson) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->