Task: goto: add a task to an existing story

Table of Contents

This page documents a task in the compass goto: start a unit of work in one command story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Extend compass goto so it can also start work on an existing story: branch + add a task to that story, instead of only ever creating a new story. Today goto always scaffolds a new story and fails if the slug already exists.

Status

Field Value
State DONE
Parent story compass goto: start a unit of work in one command
Now Implemented; both modes verified via –dry-run.
Waiting on Nothing.
Next Review.
Last touched 2026-05-25

Acceptance

  • Existing-story mode: compass goto --story <id-or-slug> --task-slug <slug> --task "<title>" [--description …] fetches main, creates a feature branch (feature/<task-slug>), adds a task to the resolved story (via add), sets the task #+branch:, and prints next steps.
  • --story resolves by :ID: (UUID or unambiguous prefix) or by the story's folder slug, using doc_index.
  • --story is mutually exclusive with the new-story flags (--slug=/–title=/=–description=); a clear error if both/neither are given.
  • New-story mode is unchanged; --dry-run works for both.

Plan

Interface decision ("have a think"): keep the current new-story mode and add an existing-story mode keyed on --story:

  • --story <id-or-slug> → existing-story mode. Resolve via doc_index: if the value is hex it matches a story :ID: (or prefix); otherwise it matches the story folder name (slug). Accepting both keeps it ergonomic (humans know slugs; tooling/links know UUIDs).
  • Required with --story: --task-slug and --task (title); --description optional. Branch defaults to feature/<task-slug>.
  • Mutually exclusive with --slug=/–title=/=–description= (new-story).

Steps:

  1. Add --story / --task-slug to cmd_goto's argparse; validate the two modes are not mixed.
  2. resolve_story(ident) → (story_dir, story_title) via doc_index.
  3. In existing mode: branch from task-slug; skip story creation; one add task --parent-dir <story_dir>; set #+branch; next steps.
  4. Dry-run + dogfood; update component overview + the goto recipe.

Notes

Verified via --dry-run for both modes (existing-story by folder slug and by :ID: prefix; new-story unchanged) and the three error paths (mixed modes, --story without task, unknown story). The execution path (git switch + add task --parent-dir) is the one already exercised by new-story goto and by add.

PRs

PR Title
#838 [ores.compass] goto: add existing-story mode (–story)

Review

Comment summary File Decision Notes
       

Result

cmd_goto now has two modes. Existing-story mode: goto --story <id-or-slug> --task-slug <slug> --task "<title>" [--description …] resolves the story via resolve_story (by :ID: exact/prefix or folder slug), branches feature/<task-slug>, adds a task to the existing story (add), sets #+branch, and prints next steps. New-story mode is unchanged. The two modes are mutually exclusive with clear validation.

Emacs 29.1 (Org mode 9.6.6)