diff --git a/.living_spec/README.md b/.living_spec/README.md index b57fedc..a06509d 100644 --- a/.living_spec/README.md +++ b/.living_spec/README.md @@ -50,7 +50,7 @@ When the user asks for a feature, follow this 4-step loop strictly: * **User Story:** "As a user, I want..." * **Acceptance Criteria:** Bullet points of observable success. * **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy -* **Git:** The Assistant initiates a new local feature branch (e.g., `feature/story-name`) immediately. +* **Git:** Make a local feature branch for the story, named from the story (e.g., `feature/story-33-camera-format-auto-selection`). You must create and switch to the feature branch before making any edits. ### Step 2: The Spec (Digest) * **Action:** Update the files in `specs/`. @@ -66,17 +66,81 @@ When the user asks for a feature, follow this 4-step loop strictly: ### Step 4: Verification (Close) * **Action:** Write a test case that maps directly to the Acceptance Criteria in the Story. -* **Action:** Run compilation and make sure it succeeds without errors. Fix warnings if possible. Run tests and make sure they all pass before proceeding. Ask questions here if needed. -* **Action:** Ask the user to accept the story. **Wait for user acceptance.** +* **Action:** Run compilation and make sure it succeeds without errors. Consult `specs/tech/STACK.md` and run all required linters listed there (treat warnings as errors). Run tests and make sure they all pass before proceeding. Ask questions here if needed. +* **Action:** Do not accept stories yourself. Ask the user if they accept the story. If they agree, move the story file to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary). * **Action:** When the user accepts: - 1. Mark the acceptance criteria as complete (change `[ ]` to `[x]`) - 2. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`) - 3. Commit both changes to the feature branch - 4. Perform the squash merge: `git merge --squash feature/story-name` - 5. Commit to master with a comprehensive commit message - 6. Delete the feature branch: `git branch -D feature/story-name` + 1. Move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`) + 2. Commit both changes to the feature branch + 3. Perform the squash merge: `git merge --squash feature/story-name` + 4. Commit to master with a comprehensive commit message + 5. Delete the feature branch: `git branch -D feature/story-name` * **Important:** Do NOT mark acceptance criteria as complete before user acceptance. Only mark them complete when the user explicitly accepts the story. +**CRITICAL - NO SUMMARY DOCUMENTS:** +* **NEVER** create a separate summary document (e.g., `STORY_XX_SUMMARY.md`, `IMPLEMENTATION_NOTES.md`, etc.) +* **NEVER** write terminal output to a markdown file for "documentation purposes" +* The `specs/` folder IS the documentation. Keep it updated after each story. +* If you find yourself typing `cat << 'EOF' > SUMMARY.md` or similar, **STOP IMMEDIATELY**. +* The only files that should exist after story completion: + * Updated code in `src/` + * Updated specs in `specs/` + * Archived story in `stories/archive/` + +--- + + +## 3.5. Bug Workflow (Simplified Path) + +Not everything needs to be a full story. Simple bugs can skip the story process: + +### When to Use Bug Workflow +* Defects in existing functionality (not new features) +* State inconsistencies or data corruption +* UI glitches that don't require spec changes +* Performance issues with known fixes + +### Bug Process +1. **Document Bug:** Create `bugs/bug-N-short-description.md` with: + * **Symptom:** What the user observes + * **Root Cause:** Technical explanation (if known) + * **Reproduction Steps:** How to trigger the bug + * **Proposed Fix:** Brief technical approach + * **Workaround:** Temporary solution if available +2. **Fix Immediately:** Make minimal code changes to fix the bug +3. **Archive:** Move fixed bugs to `bugs/archive/` when complete +4. **No Spec Update Needed:** Unless the bug reveals a spec deficiency + +### Bug vs Story +* **Bug:** Existing functionality is broken → Fix it +* **Story:** New functionality is needed → Spec it, then build it +* **Spike:** Uncertainty/feasibility discovery → Run spike workflow + +--- + +## 3.6. Spike Workflow (Research Path) + +Not everything needs a story or bug fix. Spikes are time-boxed investigations to reduce uncertainty. + +### When to Use a Spike +* Unclear root cause or feasibility +* Need to compare libraries/encoders/formats +* Need to validate performance constraints + +### Spike Process +1. **Document Spike:** Create `spikes/spike-N-short-description.md` with: + * **Question:** What you need to answer + * **Hypothesis:** What you expect to be true + * **Timebox:** Strict limit for the research + * **Investigation Plan:** Steps/tools to use + * **Findings:** Evidence and observations + * **Recommendation:** Next step (Story, Bug, or No Action) +2. **Execute Research:** Stay within the timebox. No production code changes. +3. **Escalate if Needed:** If implementation is required, open a Story or Bug and follow that workflow. +4. **Archive:** Move completed spikes to `spikes/archive/`. + +### Spike Output +* Decision and evidence, not production code +* Specs updated only if the spike changes system truth --- @@ -88,6 +152,7 @@ When the LLM context window fills up (or the chat gets slow/confused): 3. **Handoff:** The only context the new LLM needs is in the `specs/` folder. * *Prompt for New Session:* "I am working on Project X. Read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `stories/` to see what is pending." + --- ## 5. Setup Instructions (For the LLM)