One Step Ahead

One Step Ahead is a web tool for people who freeze when a task feels too big: instead of generating a plan, it surfaces exactly one tiny, concrete action — under two minutes.

Comment

One Step Ahead — Devpost Submission Package

Copy each section below into the matching Devpost form field. Items marked [HUMAN] still need your action before submitting.

1. Project name and tagline

One Step Ahead — Don't hand me a plan. Hand me the next 30 seconds.

2. Inspiration

Maya is 24, a grad student with ADHD, and she has a research paper due Friday. Today she has opened her laptop four times. Each time she looks at the words "Write research paper," feels a wall of dread come down, and closes the lid again. Nothing is wrong with her intelligence, her skills, or her intentions. What's broken is the handoff between wanting to do the thing and starting the thing.

So she tries the tools that promise to help. The task app wants her to break the paper into subtasks — which is itself a task she can't start. The shiny new AI planner is worse: it hands back a tidy 10-step checklist, which is the inside of her head rendered on a screen. The mountain, itemized. She closes the laptop a fifth time.

The insight behind One Step Ahead is that Maya doesn't need a plan. Plans are content; her problem is activation. What she needs is the next 30 seconds — one action so small and so concrete that starting it is easier than avoiding it. And if even that step feels too heavy, one tap makes it smaller. And smaller. Down to "Take one slow breath."

Transparency note: Maya is a composite persona built from widely documented experiences of ADHD and executive dysfunction, not a real individual. This project contains no real quotes, no user data, and no testimonials — no user studies have been run yet (see Limitations).

3. The Problem

The one barrier: executive-dysfunction paralysis — the freeze that happens when a person can see the size of a task. The moment the whole mountain is visible, starting becomes physically hard. This affects people with ADHD, people with depression, chronic procrastinators, and honestly anyone who has ever reorganized their desk to avoid writing a first sentence.

Why existing tools make it worse: every task-list app and AI planner is optimized for planning, not starting. They compete on how beautifully they render the full breakdown. For someone whose barrier is the sight of the mountain, a 10-step checklist is not a solution — it is the problem, formatted nicely. Time-to-first-action gets longer, not shorter, because now there's a plan to feel guilty about ignoring.

4. What It Does

One Step Ahead is deliberately almost empty:

  1. Start: one question — "What's the big thing you're avoiding?" — and one button: "Show me the first step."
  2. Step: you see exactly one micro-step, in large, calm, plain language. Under two minutes, near-zero decisions. Two buttons: Done ✓ (get the next single step) and Too heavy (get a strictly smaller one — repeatable, all the way down to "Breathe.").
  3. You never see a step count, a progress bar, a full list, or a future step — anywhere in the UI or the DOM. That's the core design principle, and it's enforced in code.
  4. Gentle momentum only: after each Done, a short warm line ("That counts.") and a small tally that only counts up ("3 steps so far"). No streaks, no guilt, no red.
  5. Quiet support actions: "Take a break" (saves state; resume later or after a refresh), "This step doesn't fit" (a different step, same size), and "Start over with a new goal."
  6. Completion: when the model judges the goal is finished, a calm "You did it." screen. Nothing confetti-shaped.

5. Before and After

Typical AI planner One Step Ahead
Time to first action 5–20 min of generating and reading a plan before any work begins Designed for under a minute: type one line, get one step
What she sees "10 steps to write your research paper: 1. Choose topic… 2. Gather sources…" "Open a blank document and title it 'Paper Draft'."
What she feels The whole mountain, itemized. Dread with a progress bar "That's… it? I can do that."
When it's still too big Re-plan, or push through the guilt One tap: "Too heavy" → "Sit where this usually happens."
After 5 opens today Zero progress, plus a plan to feel bad about A file exists, titled "Paper Draft"

(Before/after rows describe designed behavior, not measured study results.)

6. How We Built It

Architecture — deliberately boring and dependency-free:

  • Frontend: plain HTML, CSS, and vanilla JavaScript. No framework, no build step. It runs by opening index.html, from any static server, or from the included 55-line Node proxy.
  • Proxy (live mode): server.js (Node 18+, zero npm dependencies, < 60 lines) serves the static files and forwards step requests to the Anthropic Messages API. The API key is read only from the environment, never committed, never sent to the browser. Model and port come from config.
  • Demo mode: demo-engine.js is a built-in offline engine with hand-written micro-steps for three sample goals (writing, coding, a dreaded email) plus a generic fallback ladder. It powers no-key/no-network use (clearly badged "Demo mode") and acts as the safe-step fallback when the model misbehaves.
  • State: in memory plus localStorage (wrapped in try/catch), so refresh and "Take a break" resume exactly where you left off.

Prompt design — the one-step contract:

  • The model must reply with exactly one micro-step as strict JSON — no preamble, no markdown, no lists. Persona: a calm coach for executive dysfunction. Hard rules: one action, ≤ 20 words, starts with a verb, concrete, doable without deciding or planning anything. Forbidden: future steps, multi-part steps, "and then", vague verbs ("plan", "research", "figure out", "work on"), pressure language, emojis.
  • The shrink ladder: "Too heavy" sends the rejected step plus a shrink level. Level 1 = just open/look; level 2 = body-only setup; level 3+ = pure physical or sensory actions. The demo engine mirrors this with a deterministic seven-rung ladder down to "Breathe."
  • Validation and fallbacks: every model reply is schema-validated in the browser (length, verb start, no lists, no future steps, seconds ≤ 120, encouragement ≤ 12 words). Invalid output triggers up to two corrective retries; if it still fails, a built-in safe step is served. No server, no key, network failure, or a 15-second timeout each degrade gracefully — the app never dead-ends. Temperature is fixed at 0.4 server-side for consistency, and the conversation context is capped at the last 8 completed steps to keep tokens and latency low.
  • All prompts live as editable constants in prompts.js, with few-shot examples for a writing task, a coding task ("Fix bug in auth service"), a household task, and an emotional-admin task ("Reply to the email I've been avoiding"), plus a completion example.

7. Accessibility Decisions

  • WCAG 2.2 AA as a floor, not a stretch goal: every text/background pair in both light and dark themes passes 4.5:1 — verified numerically by an automated test that parses the CSS variables and computes contrast ratios.
  • Keyboard-first: Enter submits the goal; Enter on the step screen counts as Done; a logical tab order; visible focus rings (3px, offset); skip link.
  • Screen readers: semantic HTML, one h1 per screen, labeled input, aria-live="polite" announcements when the step changes, focus moved to the new step.
  • Motion and themes: prefers-reduced-motion disables all animation; prefers-color-scheme switches a calm light/dark palette via CSS variables.
  • Reading: step text is 40px on desktop (≥ 26px at 320px), touch targets ≥ 48px (primary buttons 56px), one focal point per screen, generous whitespace. Two quiet toggles: Bigger text and Easier reading (dyslexia-friendlier stack with increased letter/word spacing — a CSS-based, offline-safe interpretation of an OpenDyslexic-style option).
  • Calm by construction: soft neutrals, one muted pine accent, no red anywhere, no flashing, no countdown timers — the only time estimate is a static "Takes about 30 seconds."

8. Challenges

  • Making the model refuse to plan. LLMs are trained to be helpful, and "helpful" usually means lists. It took a strict JSON-only contract, few-shot examples, and client-side validation (with corrective retries) to reliably get one single step.
  • "Strictly smaller" is easy to say and hard to guarantee. We encode shrink semantics twice: in the prompt (levels with examples) and in the demo engine (a deterministic ladder with an entry point based on the rejected step's size, so the replacement is always lighter).
  • Proving the one-step invariant. "Never more than one step anywhere in the UI or DOM" meant no hidden containers, no console output, no future-step arrays in saved state — enforced by automated static checks and verified in a real browser.
  • Testing failure paths honestly. We drove a real headless browser against mock servers that return 500s, hang forever, or answer POSTs with static-file servers (which, it turns out, return 501 — a bug we found and fixed).

9. Limitations (the honest list)

  • Not a medical or therapeutic tool. It's a starting aid; it is no substitute for professional support or treatment.
  • Live-mode quality depends on the LLM. The offline demo engine is fixed content; the live engine is only as good as the model's adherence to the one-step contract. We mitigated with validation and fallbacks, but a bad model reply can still cost a retry cycle.
  • English-first. Steps are generated in the goal's language when live, but our verb validation is English-only (relaxed for non-Latin scripts), and the demo engine is English-only.
  • No user studies have been run. All claims about "time to first action" are design targets, not measurements. The Maya persona is a composite.
  • Demo mode is limited: three curated goals plus a generic ladder; demo "completion" is the end of a sample breakdown, clearly labeled as such.
  • Privacy: in live mode, the goal text and the last few completed steps are sent to the Anthropic API through your own proxy. No analytics, no accounts, no tracking; local state stays local.

10. What We Learned

  • Smallness is a feature you have to defend. Every review pass found something tempting to add (progress bars, streaks, step counts) that had to be cut against the same test: does this reduce Maya's cognitive load or add to it?
  • Prompts are UX. The product's personality lives in a schema and a forbidden-word list as much as in the UI.
  • Fallbacks ARE the product. For a tool aimed at people having a hard day, the no-key, no-network, and timeout paths are not error states — they're the moments the design is actually tested.
  • Skeptical testing pays: the bugs we're proudest of finding were only visible by actually running the app — a hidden-button misclick, a cross-origin abort masquerading as a network error, and a Python static server answering POST with 501.

11. What's Next

  • Run real user studies with ADHD communities (with consent and IRB where appropriate) to test whether one-step-first actually reduces time-to-start.
  • Non-English verb validation and localized demo ladders.
  • An on-device/small-model mode for fully private step generation.
  • A "new tab" browser extension variant — the start screen where paralysis already lives.
  • Gentle, local-only history ("you've started 14 things this month") with no streak mechanics.

12. Built With

  • Plain HTML5, CSS (custom properties, media queries), and vanilla JavaScript — no frontend framework, no build step
  • Node.js standard library only (http, fs, built-in fetch) — zero npm dependencies
  • Anthropic Messages API (Claude) in live mode, via a < 60-line proxy
  • System font stacks (no webfont downloads, works fully offline)
  • Devpost-adjacent: tested with agent-browser (headless Chromium) and a dependency-free Node test suite

14. AI Assistance and Pre-existing Work Disclosure

  • This project was built with AI coding assistance (an AI coding agent was used for scaffolding, code, tests, and documentation). All code was reviewed, executed, and tested before inclusion; the test results quoted in this submission are from actual runs.
  • The product itself calls an LLM API (Anthropic's Claude, via the user's own proxy and key) to generate steps in live mode. Demo mode is entirely deterministic, hand-written content.
  • Pre-existing code/libraries: none beyond what is listed in "Built With" (Node.js standard library, standard web platform APIs, system fonts). No third-party packages, no template code, no copied snippets.

16. Build and Run Instructions

Try it in 10 seconds (demo mode, no key):

git clone <your-repo-url> one-step-ahead
cd one-step-ahead
# Option A: double-click index.html
# Option B: any static server, e.g.
npx serve .            # or: python3 -m http.server 8000

Full mode (with an Anthropic API key):

cd one-step-ahead
cp .env.example .env
# edit .env: ANTHROPIC_API_KEY=sk-ant-...
npm start              # needs Node 18+; nothing to install
# open http://localhost:3000
  • Without a key, the app automatically runs in Demo mode (badged in the UI) — including with the network fully disabled or straight from the filesystem.
  • Run the test suite: npm test (73 checks) — validator, shrink logic, persistence, retry/fallback paths, WCAG contrast, and static safety checks.
  • Browser end-to-end regression: bash e2e.sh (28 checks, needs the server running and the agent-browser CLI).
Share this project:

Updates

Submission history