---
name: file-justification
description: "Guide and workflow for File Justification Protocol. Use when you need File Justification Protocol."
---

# File Justification Protocol

**Purpose**: Before creating or modifying ANY file, you MUST document the justification to prevent unnecessary file creation and ensure changes are well-reasoned.

## When This Protocol Applies

- Creating a NEW file (highest scrutiny)
- Modifying an EXISTING file
- All PR changes (each file touched needs justification)

## Justification Template

For EACH file you touch, document:

```
### File: <filename>

**GOAL**: What are you trying to achieve?
**MODIFICATION**: What specific change are you making?
**NECESSITY**: Why is this change required? Why can't it be done differently?
**INTEGRATION PROOF**: How does this integrate with existing code?
```

## New File Creation - Extreme Scrutiny

**Default: NO NEW FILES** - You must prove why integration into existing files is impossible.

### Pre-Write Checklist (MANDATORY before creating any new file)

1. **Assume existing files can handle it** - Search for similar functionality
2. **Identify integration targets** - Which existing files could contain this code?
3. **Attempt integration first** - Try adding to existing file before creating new
4. **Document why integration failed** - Concrete reason, not "cleaner this way"

### Integration Hierarchy (try in order)

1. Existing file with similar functionality
2. Existing utility/helper file
3. Existing `__init__.py`
4. Existing test file (for test code)
5. Existing class as a method
6. Config file
7. **LAST RESORT**: New file (with full justification)

## Examples

### Good Justification (Modifying Existing)
```
### File: mvp_site/llm_response.py

**GOAL**: Add backward compatibility for outcome_resolution field
**MODIFICATION**: Add property that falls back to outcome_resolution when action_resolution is missing
**NECESSITY**: API clients already use action_resolution; changing the field name would break them
**INTEGRATION PROOF**: Property pattern matches existing properties in this class (lines 45-67)
```

### Good Justification (New File - Justified)
```
### File: mvp_site/action_resolution_utils.py (NEW)

**GOAL**: Centralize action_resolution/outcome_resolution fallback logic
**MODIFICATION**: Create helper module with get_action_resolution() function
**NECESSITY**: Same logic duplicated in llm_response.py (22 lines) and world_logic.py (13 lines)
**INTEGRATION PROOF**:
- Could not add to llm_response.py - world_logic.py would create circular import
- Could not add to world_logic.py - llm_response.py would create circular import
- New utils file breaks the dependency cycle
```

### Bad Justification (Rejected)
```
### File: mvp_site/new_helper.py (NEW)

**GOAL**: Add helper function
**MODIFICATION**: Create new file with helper
**NECESSITY**: Cleaner to have it separate  <-- NOT VALID
**INTEGRATION PROOF**: None attempted  <-- MUST ATTEMPT
```

## File Placement Rules

If a new file is justified, place it correctly:

| Code Type | Location |
|-----------|----------|
| Python module | `mvp_site/` or appropriate submodule |
| Scripts | `scripts/` |
| Tests | `mvp_site/tests/` |
| Commands | `.claude/commands/` |
| Skills | `.claude/skills/` |

**NEVER** create new files in project root.

## Banned Patterns

- `*_v2.py` - Edit existing file
- `*_new.py` - Edit existing file
- `*_backup.py` - Use git
- `*_old.py` - Delete and replace

## Quick Reference

Before ANY file operation:
1. What existing file could contain this? (Search first)
2. Why can't I add this to that file? (Valid reason required)
3. Have I documented GOAL/MODIFICATION/NECESSITY/INTEGRATION PROOF?

**If you cannot answer these questions, do not create the file.**