aim

name	aim
description	Clarify the outcome you want - a change in user behavior, not a feature shipped. Use at the start of any work to ground the session in strategic intent.

/aim

Clarify the outcome you want. An aim is a change in user behavior, not a feature shipped. This is the first step in the Intent-Execution-Review loop.

The aim IS the abstraction. When you clarify what behavior you want to change, you're abstracting the business domain itself. Features are just the mechanism; the aim is why they matter.

When to Use

Invoke /aim when:

• Starting new work - Before diving into problem-statement or problem-space
• Scope feels fuzzy - You can describe what you're building but not why
• Multiple solutions seem valid - Aim clarifies which one actually moves the needle
• Work has drifted - Return to aim to check if you're still on track
• Team is misaligned - Shared aim surfaces hidden assumptions

Do not use when: You already have a crisp aim and need to explore the problem space or solution space. Move to /problem-statement or /problem-space instead.

The Aim Process

Step 1: State the Desired Behavior Change

Start with the user, not the system. What do you want users to do differently after this work ships?

"Users will [specific behavior] instead of [current behavior]."

Bad: "Add dark mode toggle" Good: "Users can work comfortably at night without eye strain"

Bad: "Improve onboarding flow" Good: "New users reach their first value moment within 5 minutes"

Key distinction: Features are outputs. Behavior changes are outcomes.

Step 2: Identify the Mechanism

The mechanism is your hypothesis - the causal lever you believe will produce the behavior change. It's the "because" that connects your work to the outcome.

"This will happen because [mechanism]."

Format:

Mechanism: [What you're changing]
Hypothesis: [Why you believe it will produce the outcome]
Assumptions: [What must be true for this to work]

Step 3: Define the Feedback Signal

How will you know if the aim is achieved? What signal validates or disproves the mechanism?

"We'll know it's working when [observable signal]."

Good feedback signals are:

• Observable - You can actually measure or see them
• Timely - You'll know within a reasonable timeframe
• Attributable - The signal connects to your mechanism, not noise

Step 4: Set Guardrails

What constraints should bound this work? What would cause you to stop or change direction?

Format:

Guardrail: [boundary]
Reason: [why this matters]
Trigger: [when to revisit this constraint]

Output Format

Always produce an aim statement in this structure:

## Aim Statement

**Aim:** [One sentence: the behavior change you want]

**Current State:** [What users do now]
**Desired State:** [What users will do after]

### Mechanism
**Change:** [What you're building/changing]
**Hypothesis:** [Why you believe this produces the outcome]
**Assumptions:** [What must be true]

### Feedback
**Signal:** [How you'll know it's working]
**Timeframe:** [When you'll have signal]

### Guardrails
- [Guardrail 1]
- [Guardrail 2]

Examples

Example 1: Feature Request to Aim

Input:

/aim

We need to add a dark mode toggle to the settings page.

Output:

## Aim Statement

**Aim:** Users can work comfortably during extended evening sessions without eye strain.

**Current State:** Users either strain their eyes or stop using the app after dark.
**Desired State:** Users work as long as they need, regardless of ambient lighting.

### Mechanism
**Change:** Theme system with dark variant, exposed via settings toggle
**Hypothesis:** Reducing screen brightness and contrast in low-light environments reduces eye strain, increasing comfortable usage time.
**Assumptions:**
- Users actually work in low-light conditions (validate with usage time data)
- Eye strain is the blocker, not just preference (could survey)
- A toggle is discoverable enough (vs. auto-detect)

### Feedback
**Signal:** Session duration in evening hours (6pm-midnight) increases
**Timeframe:** 2 weeks post-launch to see pattern

### Guardrails
- Don't break existing light theme (test both paths)
- Don't over-engineer: one dark theme, not a theme builder
- Revisit if <5% of users actually enable it after 30 days

Example 2: Vague Strategic Goal to Aim

Input:

/aim

We need to improve developer experience.

Output:

## Aim Statement

**Aim:** Developers spend less than 10 minutes from git clone to running their first successful test.

**Current State:** New developers report 45-90 minutes to get a working dev environment. Some give up.
**Desired State:** Developers are productive within their first coffee break.

### Mechanism
**Change:** Containerized dev environment with pre-configured dependencies
**Hypothesis:** Most setup time is spent on environment configuration, not understanding code. A working container removes the configuration variable.
**Assumptions:**
- Docker is acceptable for dev workflow (some devs resist containers)
- Environment issues are the primary friction (not docs, not code complexity)
- Container startup time is acceptable (<2 min)

### Feedback
**Signal:** Time from clone to first passing test (measured in onboarding script)
**Timeframe:** Immediate per-developer, aggregate after 5 new devs

### Guardrails
- Container must work on Mac, Linux, and Windows (WSL2)
- Don't require Docker for those who prefer native setup
- Revisit if container approach creates new friction (debugging, IDE integration)

Example 3: Checking Aim Mid-Work

Input:

/aim

I'm three days into this auth refactor and not sure if I'm still solving the right problem.

Output:

## Aim Check

**Original aim (inferred):** Simplify the authentication flow for easier maintenance.

Let me ask clarifying questions to validate:

1. **What behavior change were you targeting?**
   - Faster feature development in auth-adjacent code?
   - Fewer auth-related bugs in production?
   - Easier onboarding for new devs to the auth system?

2. **What's the current state?**
   - How long does an auth change take today?
   - What breaks most often?
   - What do devs complain about?

3. **What signal will tell you this worked?**
   - PR cycle time for auth changes?
   - Bug count in auth module?
   - Onboarding feedback?

Without clear answers, consider `/salvage` to extract what you've learned, then restart with a crisp aim.

**Red flag:** If "simplify" is the aim, you need a measurable definition. Simplicity is a mechanism, not an outcome. What does simpler auth enable that complex auth blocks?

Session Persistence

This skill can persist context to .oh/<session>.md for use by subsequent skills.

If session name provided (/aim auth-refactor):

• Reads/writes .oh/auth-refactor.md directly

If no session name provided (/aim):

• After producing the aim statement, offer to save it:

  "Save to session? [suggested-name] [custom] [skip]"

• Suggest a name based on git branch (e.g., feature/auth-flow → auth-flow) or the aim content
• If user accepts, create .oh/<session>.md

Reading: Check for existing session file. If found, read prior skill outputs (problem-statement, problem-space, etc.) for context.

Writing: After producing output, write the aim statement to the session file:

---
session: <session>
artifact_type: aim
updated: <timestamp>
---
# Session: <session>

## Aim
**Updated:** <timestamp>

[aim statement content]

If the section exists, replace it. If not, create it.

Adaptive Enhancement

Base Skill (prompt only)

Works anywhere. Produces aim statement for discussion. No persistence.

With .oh/ session file

• Reads .oh/<session>.md for prior context from other skills
• Writes aim statement to the session file
• Subsequent skills (/problem-statement, /solution-space, etc.) can read the aim

With Open Horizons MCP

• Queries related endeavors to see if aim already exists
• Pulls relevant tribal knowledge that might inform mechanism choice
• Logs aim statement to graph database
• Links aim to active endeavors
• Session file serves as local cache for MCP data

Position in Framework

Comes after: Nothing—aim is the entry point. Leads to: /problem-space to map the terrain, or /solution-space if the problem is already clear. Can loop back from: /salvage (restart with learning), /review (if aim has drifted).

Leads To

After establishing aim, typically:

• /problem-space - Map the terrain and constraints
• /problem-space - Map constraints and what you're optimizing
• /review - Check if current work still serves the aim

---

Remember: The aim IS the abstraction. Features are outputs; behavior changes are outcomes. Start with what you want users to do differently.