Standardize

Phase 0: Workspace Setup

Before starting standardization, determine where to work.

0.1 Check Current State

Run the workspace check script to understand the current environment:

.claude/skills/standardize/scripts/check-workspace.sh

This reports: current branch, worktree status, uncommitted changes, remote tracking, existing worktrees, and recent commits - all in a single invocation.

0.2 Ask About Worktree

Use AskUserQuestion:

Where should I apply this standardization?

**Option A: New worktree** (Recommended for large scopes)
- Creates isolated workspace branched from origin/main
- Copies .env files automatically
- Safe for sweeping changes across many files
- Allows multiple agents to work simultaneously

**Option B: Current worktree**
- Creates branch from origin/main in current checkout
- Simpler, no setup overhead
- Good for small, contained scopes

0.3 Set Up Workspace

If new worktree - run the setup script:

.claude/skills/standardize/scripts/setup-worktree.sh "refactor/standardize-<convention>"

This automatically:

• Fetches latest from origin
• Creates a new worktree + branch from origin/main
• Copies all .env* files from the main repo
• Reports the new directory path

After it completes, cd into the new worktree directory it prints.

If current worktree:

git fetch origin main --quiet && git checkout -b refactor/standardize-<convention> origin/main

Base branch: Always origin/main unless the user explicitly specifies a different base.

Phase 1: Parse Input

Extract from $ARGUMENTS:

• Convention: What pattern/convention to apply
• Scope: Where to apply it (directory, domain, or "all")

If unclear, use AskUserQuestion to clarify:

• Which specific convention?
• What's the target scope?
• Are there any exclusions?

Phase 2: Understand the Convention

2.1 Find the Canonical Definition

Look for the convention in:

1. Existing exemplary implementations
2. Project documentation and conventions files

Use Task tool with Explore agent:

Find the canonical definition and examples of [CONVENTION]:
1. Find 2-3 existing implementations that follow the pattern correctly
2. Identify the key characteristics that define "correct" usage

2.2 If Pattern Has Variants

If there are multiple valid approaches to the convention, identify and present them:

## Pattern Variants for [Convention]

### Option A: [Name]
- **Approach**: [Description]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]

### Option B: [Name]
- **Approach**: [Description]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]

Which approach should we use?

Use AskUserQuestion to get a decision before proceeding.

Example from error handling:

• Option A: Keep domain exceptions pure, map at API boundary (cleaner separation)
• Option B: Make domain exceptions inherit from gRPC errors (automatic HTTP mapping)

2.3 Validate Architectural Fit

Before applying broadly, validate the pattern belongs at this layer:

• Layer appropriateness: Does this pattern belong in domain, API, or infrastructure?
• Coupling concerns: Are we coupling things that should be separate?
• Dependency direction: Does this respect the dependency flow (all dependencies flow inward to core)?

If uncertain, discuss with the user:

## Architectural Consideration

The proposed pattern would [describe what it does].

This means [layer X] would now depend on [layer Y].

Is this the right architectural choice, or should we keep these concerns separate?

2.4 Document the Target State

Summarize what "correct" looks like:

## Convention: [Name]

### Correct Pattern
[Description of how it should be done]

### Example (from codebase)
`path/to/exemplary/file.py:123`
```python
# Correct implementation
[code snippet]

Anti-pattern (what we're fixing)

# Incorrect/legacy implementation
[code snippet]

Key Indicators

• [What to search for to find violations]
• [Patterns that indicate old/wrong usage]

### Phase 3: Find Violations

#### 3.1 Search for Anti-patterns

Use targeted searches to find code that doesn't follow the convention:

Use Task tool with Explore agent:

Find all violations of [CONVENTION] in [SCOPE]:

1. Search for anti-pattern indicators
2. Check each file for old/inconsistent usage
3. Categorize findings by file/module
4. Note the specific changes needed for each

#### 3.2 Categorize Findings

Group violations by:
- **Simple**: Direct replacement, low risk
- **Complex**: Requires refactoring, affects multiple files
- **Uncertain**: Needs human judgment

```markdown
## Violations Found

### Simple (direct replacement)
| File | Line | Current | Should Be |
|------|------|---------|-----------|
| `path/file.py` | 45 | `raise OldException()` | `raise NewException()` |

### Complex (requires refactoring)
- `path/complex.py`: [Description of what needs changing]

### Uncertain (needs review)
- `path/edge_case.py`: [Why this is unclear]

Phase 4: Breaking Change Risk Assessment

CRITICAL: Before applying changes, evaluate impact on external consumers.

4.1 Identify API Contract Changes

Check if the standardization will change:

• HTTP status codes: Will error responses return different status codes?
• Error response structure: Will field names or format change?
• Error codes/messages: Do consumers key off specific error strings?

4.2 Categorize Risk Level

4.3 Present Breaking Changes

If HIGH RISK changes are identified:

## ⚠️ Breaking Change Warning

The following changes may break existing API integrations:

| Scenario | Before | After | Risk |
|----------|--------|-------|------|
| Metric not found | HTTP 500 | HTTP 404 | Customers checking `status == 500` will break |
| Duplicate metric | HTTP 500 | HTTP 409 | Customers checking `status == 500` will break |

### Options
1. **Proceed anyway**: Accept the breaking change (may require customer communication)
2. **Maintain backwards compatibility**: Keep old behavior, add new pattern alongside
3. **Scope reduction**: Exclude high-risk endpoints from this standardization

Which approach should we take?

Use AskUserQuestion to get explicit approval for breaking changes.

Phase 5: Present Plan and Get Approval

CRITICAL: Get explicit approval before making changes.

Present:

1. Summary of convention being applied
2. Number of files affected
3. Categorized list of changes
4. Any uncertain cases that need human decision

## Standardization Plan: [Convention] in [Scope]

### Summary
- **Files affected**: [N]
- **Simple changes**: [N]
- **Complex changes**: [N]
- **Uncertain cases**: [N]

### Changes Preview
[Show representative examples of each category]

### Uncertain Cases
[List any that need human decision]

---

Should I proceed with these changes?
- Yes, apply all changes
- Yes, but skip uncertain cases
- Let me review the uncertain cases first
- No, let's adjust the scope

Use AskUserQuestion to get approval and handle uncertain cases.

Phase 6: Apply Changes

6.1 Apply Simple Changes First

For each simple change:

1. Make the edit
2. Verify syntax is correct
3. Move to next

6.2 Apply Complex Changes

For each complex change:

1. Read the full context
2. Apply the refactoring
3. Check for ripple effects (imports, callers)
4. Update related code if needed

6.3 Handle Edge Cases

For uncertain cases (if user approved):

1. Apply conservatively
2. Add TODO comment if truly ambiguous
3. Note in summary for manual review

Phase 7: Verification

7.1 Run Linting

Run the project's linting suite (e.g., task lint, make lint, npm run lint).

Fix any issues introduced by the changes.

7.2 Run Tests

Run the project's test suite (e.g., task test, make test, pytest, npm test).

If tests fail:

1. Identify if failure is due to our changes
2. Fix the issue
3. Re-run tests

7.3 Verify Consistency

Quick check that no violations remain in scope:

Search for anti-pattern indicators in [SCOPE]
Confirm all have been addressed

Phase 8: Summary

Provide a complete summary:

## Standardization Complete: [Convention] in [Scope]

### Changes Made
- **Files modified**: [N]
- **Simple replacements**: [N]
- **Complex refactors**: [N]
- **Skipped (uncertain)**: [N]

### Files Changed
- `path/to/file1.py`: [Brief description]
- `path/to/file2.py`: [Brief description]
- ...

### Verification
- Linting: ✅ Passing
- Tests: ✅ Passing
- No remaining violations in scope

### Notes
- [Any edge cases or follow-up items]
- [Files that might need manual review]

Phase 9: Pull Request

After verification passes, offer to create a PR.

9.1 Ask About PR Creation

Use AskUserQuestion:

Standardization complete and verified. Would you like me to open a Pull Request?

- Yes, create PR targeting main/master
- Yes, but target a different branch
- No, I'll handle the PR myself

9.2 Create the PR

If approved, create the PR:

git add -A
git commit -m "refactor: standardize <convention> in <scope>

Applied <convention> consistently across <N> files.
No functional changes - pattern consistency only."

git push -u origin <branch-name>

gh pr create --title "refactor: standardize <convention> in <scope>" --body "## Summary
<1-2 sentences explaining what convention was applied and where>

## Problem
<Why this standardization was needed - inconsistency, tech debt, etc.>

## Solution
<The pattern/convention that was applied - 2-4 bullet points>
- Before: <old pattern>
- After: <new pattern>

## Changes
- **Files modified**: <N>
- **Simple replacements**: <N>
- **Complex refactors**: <N>

### Files Changed
- \`path/to/file1.py\`: <what changed>
- \`path/to/file2.py\`: <what changed>

## Testing
- All existing tests pass
- No functional changes - pattern consistency only

## Notes for Reviewers
<optional - any edge cases, files skipped, follow-up work needed>"

Claude PR review will automatically add deeper analysis after the PR is created.

9.3 Clean Up Worktree (If Applicable)

If working in a separate worktree, offer cleanup:

Use AskUserQuestion:

PR created. Would you like me to clean up the worktree?

- Yes, remove the worktree and switch back to main repo
- No, keep the worktree around

If yes, run the cleanup script:

.claude/skills/standardize/scripts/cleanup-worktree.sh

This checks for uncommitted changes, navigates back to the main repo, and removes the worktree.

9.4 Remaining Work

If there are items outside the original scope:

### Remaining Work (if any)
- [Items outside scope that also need updating]
- [Related conventions that might benefit from standardization]

Common Conventions to Standardize

Error Handling

Target: Consistent error/exception types across the codebase Anti-pattern: Mixed exception styles, HTTPException in services, bare except Exception Scope: Usually by domain or layer

Repository Pattern

Target: Repository interface in domain/core, implementation in infrastructure Anti-pattern: Direct query calls, business logic in repositories Scope: By domain

Type Hints

Target: Full type hints on all function signatures Anti-pattern: Missing hints, Any without justification Scope: By module

Logging

Target: Consistent structured logging throughout the codebase Anti-pattern: Print statements, inconsistent log levels or formats Scope: Entire codebase

Docstrings

Target: Consistent docstring format on public APIs Anti-pattern: Missing docstrings, mixed formats Scope: By module

Guidelines

Be Systematic

• Don't skip files in scope
• Apply the same transformation consistently
• Track progress through the scope

Be Conservative

• When in doubt, ask
• Don't change code you don't understand
• Preserve behavior while changing implementation

Verify Thoroughly

• Run tests after each batch of changes
• Check for ripple effects
• Confirm no regressions

Document Edge Cases

• Note any files that couldn't be standardized
• Explain why certain code was left unchanged
• Suggest follow-up work if needed

Begin

1. Parse: $ARGUMENTS
2. Identify the convention and scope
3. If unclear, ask clarifying questions
4. Find the canonical pattern definition
5. Search for violations

Start by understanding exactly what convention to apply and where.