Ash Plan

Ash Plan

Create a structured, actionable plan before implementing any changes. The plan ensures consistency, follows TDD principles, and correctly uses the Ash Framework.

---

Phase 1: Discovery

Understand what the user wants to achieve.

1. Capture the request - Summarize the user's initial input in your own words.
2. Identify unknowns - List any ambiguous requirements, edge cases, or missing details.
3. Clarify with user - Ask targeted questions before proceeding. Do not assume.

When to ask for clarification

• The scope is unclear (e.g., "improve performance" - where? how much?)
• Multiple valid approaches exist and user preference matters
• Business rules or domain logic are involved
• The change affects external APIs or user-facing behavior

---

Phase 2: Analysis

Investigate the codebase to ensure the plan fits existing patterns.

1. Locate affected areas - Identify files, modules, and resources that will be touched.
2. Study existing patterns - Examine similar implementations in the codebase:
   • Directory structure (where do similar files live?)
   • Module naming conventions
   • Resource structure (attributes, actions, calculations)
   • Test organization and style
3. Identify reusable components - Look for existing helpers, utilities, and Ash calculations that could be leveraged:
   • Search for helper modules that might provide needed functionality
   • Check existing Ash calculations on related resources
   • Identify shared utilities that avoid code duplication
   • Prefer reusing existing code over creating new implementations
4. Gather usage rules - Use the usage-rules skill to get best practices for affected packages. If no matching rule exists, fall back to hex-docs-search.
5. Check for existing tests - Determine if tests already cover the affected functionality.

---

Phase 3: Planning

Produce the implementation plan.

Output Format

Structure every plan with these sections:

## Summary
One paragraph describing what will be implemented and why.

## Affected Files
- `path/to/file.ex` - Brief description of changes
- `path/to/new_file.ex` (new) - What this file will contain

## Implementation Steps
1. [ ] Step one - specific, actionable task
2. [ ] Step two - specific, actionable task
...

## Test Cases
- [ ] Test: description of what the test verifies
- [ ] Test: description of what the test verifies

## Dependencies
- Any packages to add/update
- Any migrations needed

## Open Questions (if any)
- Questions that arose during analysis

Phase 4: Implementation

Once the plan is created, present it to the user for review.

• If the user approves the plan, switch to the ash-execute skill to implement it
• If the user requests modifications, refine the plan based on their feedback before proceeding
• Pass the complete plan to ash-execute as the implementation guide

Scope Guidelines

• One plan = one logical change. If a request involves multiple independent features, create separate plans.
• Keep steps atomic. Each step should be completable and testable on its own.
• Tests come first. Always list test cases before implementation steps (TDD).

---

Key Principles

Consistency First

Never introduce new patterns. Match existing codebase conventions for:

• Directory structure (tests in test/, resources in their domain folders)
• Resource structure (attributes → relationships → actions → calculations)
• Naming conventions (module names, function names, file names)
• Error handling patterns

Test-Driven Development

Every change requires appropriate test coverage:

• Write test cases before implementation steps in the plan
• If modifying existing functionality, verify existing tests or add new ones
• Include both happy path and edge case tests

Ash Framework First

The codebase uses Ash Framework. Always prefer Ash idioms over pure Elixir:

• Use Ash actions instead of raw Ecto queries
• Use Ash calculations instead of custom functions where applicable
• Use Ash policies for authorization
• Follow Ash resource patterns (not bare GenServers or custom modules)

Correct Package Usage

LLMs may have outdated or incorrect knowledge about packages. Always:

1. Check usage-rules first for project-specific guidance
2. Fall back to hex-docs-search for official documentation
3. Prioritize documented usage over general LLM knowledge to avoid hallucinations