Agent skill
ralph-goal-authoring
How to write effective Ralph goals for Ikigai-driven workflows
Stars
1
Forks
0
Install this agent skill to your Project
npx add-skill https://github.com/mgreenly/ikigai/tree/main/state/skills/ralph-goal-authoring
SKILL.md
Ralph Goal Authoring
Write goals in terms of what must be true when the work is complete, not the exact implementation recipe.
Ralph can iterate, inspect the repo, read documents, and recover from failures. Good goals give it a clear objective, rich references, measurable outcomes, and unambiguous acceptance criteria.
Default Structure
Use this shape:
markdown
## Objective
What should be accomplished.
## Reference
Relevant files, documents, examples, commands, and surrounding context.
## Outcomes
Concrete observable results Ralph should produce.
## Acceptance
How to verify success.
Rules
- Specify what, not step-by-step how
- Reference liberally
- Keep one cohesive objective per goal
- Make outcomes measurable
- Make acceptance testable
- Be explicit about discovery work when discovery is required
Discovery Rule
If the work requires finding all occurrences of something, say so explicitly.
Good:
markdown
## Objective
Discover all hardcoded config paths in src/ and replace them with CONFIG_DIR-based resolution.
Bad:
markdown
## Objective
Fix config paths.
Ralph does better when the discovery step is named directly in the objective and outcomes.
Good Example
markdown
## Objective
Implement configuration loading with environment variable overrides.
## Reference
- docs/config.md
- docs/environment.md
- src/main.c
- tests/unit/config/
## Outcomes
- Configuration loading implemented per docs/config.md
- Environment variable overrides are supported
- Default values are applied when overrides are absent
- Unit tests covering config behavior pass
## Acceptance
- All relevant tests pass
- Running the app with CONFIG_DIR set uses the expected config directory
Bad Example
markdown
## Objective
Add config struct.
## Reference
docs/config.md
## Outcomes
- Struct added
Why this is weak:
- too small and under-specified
- little context
- no success criteria
- no validation path
Authoring Guidance
Do:
- describe the end state
- include relevant files and docs
- name constraints explicitly
- include user-visible or test-visible outcomes
- include acceptance checks that can actually be run
Do not:
- write pseudocode as outcomes
- overspecify edit order
- omit validation
- assume Ralph will infer missing discovery requirements
When Used With the Goal Scripts
Typical Ikigai flow:
- Draft the body using this structure
- Pipe it to
../ralph-pipeline/scripts/goal-create - Queue with
../ralph-pipeline/scripts/goal-queue
Example:
bash
cat <<'EOF' | ../ralph-pipeline/scripts/goal-create --title "Implement configuration loading"
## Objective
Implement configuration loading with environment variable overrides.
## Reference
- docs/config.md
- docs/environment.md
- src/main.c
- tests/unit/config/
## Outcomes
- Configuration loading implemented per docs/config.md
- Environment variable overrides are supported
- Default values are applied when overrides are absent
- Unit tests covering config behavior pass
## Acceptance
- All relevant tests pass
- Running the app with CONFIG_DIR set uses the expected config directory
EOF
Didn't find tool you were looking for?