Goravel Planning

Goravel Planning

Produces a complete, reviewable implementation plan before any code is written. The goal is to surface every file that needs changing, every invariant to preserve, every ambiguity that needs a decision — so that implementation can proceed without surprises.

This skill is read-only. It explores the codebase, reads relevant files, and writes a plan. It does not edit or create source files.

Workflow

Follow these steps in order. Do not start writing the plan until Steps 1–4 are complete.

Step 1: Understand the Task

Extract from the user's message:

• What is being added or changed (new feature, new endpoint, refactor, bug fix, etc.)
• Business rules — constraints, invariants, edge cases, exclusions
• Scope boundaries — what components / modules / contexts this applies to (and what it explicitly does NOT apply to)
• Ambiguities — anything the description leaves unclear

Step 2: Locate the Affected Code

Determine which service, module, or package is the primary target. Use targeted searches to understand the project layout before reading files:

# Discover project structure
find . -type f | head -40
# Locate relevant files by pattern or keyword
grep -r "<key term>" --include="*.<ext>" -l | head -20

Identify the root of the affected component and understand its layout (source files, tests, config, schema, migrations, etc.).

Step 3: Read Existing Patterns

Read the most relevant existing files to understand:

• Schema / models — data structures, naming conventions, existing values
• Core logic — existing predicates, helpers, dispatch patterns
• Validation / guards — how input is validated, what constraints are enforced
• Configuration / build — how the project is built, what tooling runs after changes
• Tests — how existing test suites are structured, what patterns look like

Read enough to know the exact code you will reference in the plan, but do not read entire files if a targeted grep suffices.

Step 4: Identify All Touch Points

Build a complete list of every file that needs to change, organized by layer. For each file, note what specifically changes and why. Common layers to consider:

Adapt this to the actual project structure — discover the equivalent layers by reading the codebase.

Step 5: Write the Plan

Output the plan in the format below. Be specific — include exact file paths, exact new identifiers, exact code snippets for non-trivial additions. The reader should be able to implement from the plan without opening the source files themselves.

Plan Output Format

## Summary

<1–3 sentence description of what is being added and the key business rules it must satisfy.>

Rules:
- <rule 1>
- <rule 2>
- ...

---

## Files to Change

### 1. <Layer name> — <one-line description>

**File:** `<exact path>`

<Explanation of what changes and why. Include the exact new code or pseudocode for non-trivial additions. For schema changes, include the full before/after. For logic changes, include the exact function signatures and key logic.>

### 2. <Layer name> — ...

...

---

## Sequence

Ordered implementation steps with dependencies called out explicitly:

1. <step> → <what it unblocks>
2. <step>
...
N. Run tests to verify

---

## Real User Code Example

the end-user application code that would use or observe the change. Do not stop at abstract steps like "update middleware" or "add validation".
Show the shape of the real code.

<Code snippet showing how a Goravel user would interact with the new feature or change>

## Open Questions

Things that must be confirmed before implementation:

1. <question> — <why it matters, what the two possible answers imply>
2. ...

(Omit this section if there are no genuine ambiguities.)

What counts as actual code

Use Actual code to show the likely implementation shape in this repository, such as:

• contracts added under contracts/
• framework wiring in foundation/ or service_provider.go
• facade or module behavior in package code
• tests that prove the framework behavior

Example:

type Middleware interface {
	Handle(ctx http.Context) error
	Name() string
}

What counts as real user code

Use Real user code to show code a Goravel application author would actually write in a real app, not internal framework implementation.

Prefer patterns from goravel/goravel and goravel/example, such as:

• route registration
• middleware usage
• controller code
• request validation
• ORM queries
• auth flows

Example:

facades.Route().Middleware(middleware.Jwt()).Get("users", userController.Index)

Quality Bar for the Plan

Before outputting, verify:

• Every file that needs changing is listed — no layer silently left out
• File paths are exact (verified by the searches in Steps 2–3)
• Code snippets use the correct identifiers (function names, type names, constant names) as they actually exist in the codebase, not guesses
• The sequence respects actual build and dependency order for this project
• Open Questions are genuine ambiguities, not things that can be determined by reading the code
• The plan does not contain implementation — only description of what to implement
• If the work affects user-facing behavior, include Real User Code Example.
• If the work is entirely internal, say that explicitly and omit the user code example only when no realistic user-facing snippet exists.
• Never use pseudo-code placeholders inside code fences. Use realistic Goravel code patterns.