| name | goravel-planning |
| description | Planning workflow for Goravel tasks. Use this skill whenever the user asks for a plan, investigation, or implementation outline and the response should show both the concrete code change and the real user-facing code that the change enables.
|
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:
find . -type f | head -40
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:
| Layer | Examples | What changes |
|---|
| Schema / models | .thrift, .proto, .sql, .graphql, type files | New fields, values, types |
| Generated code | Auto-generated stubs, clients | Rebuilt via project tooling |
| DB migrations | Migration files | Schema changes |
| Core logic | Service, handler, util files | New functions, updated dispatch |
| Validation | Validator, guard files | New rules, updated checks |
| Tests | *_test.* files | New test cases covering the change |
| Config / build | Build files, manifests | New dependencies, targets |
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.
