prompt guidance work

AGENTS.md

@@ -18,6 +18,7 @@ If implementation order changes to unblock work, update `docs/scrum-backlog.md`
 Agents must also consult:
 - `docs/decision-log.md` for accepted product and delivery decisions
 - `docs/release-mvp-checklist.md` for the current MVP completion criteria
+- `docs/prompt-process.md` for the standard prompt format and prompt-repair workflow
 
 ## 1B. Current MVP-Now Delivery Contract
 
@@ -46,6 +47,8 @@ For the current MVP, these are explicitly **not launch blockers** unless the use
 
 When this file and `docs/scrum-backlog.md` differ on near-term execution priority, use `docs/scrum-backlog.md` as the active delivery plan and keep this file as the broader product specification.
 
+If a substantial user prompt does not follow the standard structure in `docs/prompt-process.md`, agents should still help, but should also briefly show a corrected prompt in the recommended format and then proceed using that repaired structure.
+
 Build **CartWise v1**, a mobile-first grocery companion web application using **ASP.NET Core MVC**, **Razor Views**, **HTML5**, **CSS3**, **jQuery**, and **vanilla JavaScript**.
 
 CartWise v1 is not a grocery delivery platform and is not tied to any retailer. Its first job is to become the shopper's grocery memory:
@@ -1466,20 +1469,21 @@ Architectural seams may be left for later, but do not build speculative systems.
 2. Review `docs/scrum-backlog.md` before starting implementation work.
 3. Update `docs/scrum-backlog.md` as work starts, changes, and completes.
 4. Review `docs/decision-log.md` before changing near-term MVP scope or delivery assumptions.
-5. Inspect existing code before creating parallel abstractions.
-6. Prefer extending existing patterns over inventing new ones.
-7. Keep controllers thin.
-8. Keep persistence code out of Razor views and controllers.
-9. Keep external provider response types inside Infrastructure.
-10. Add tests for business rules and bug fixes.
-11. Run build/tests after meaningful changes.
-12. Do not silently change database semantics.
-13. Create migrations for schema changes; never hand-edit production schema.
-14. Never fabricate retailer capabilities or data.
+5. Use `docs/prompt-process.md` for substantial prompts and show repaired prompt examples when a user request is too informal for reliable execution.
+6. Inspect existing code before creating parallel abstractions.
+7. Prefer extending existing patterns over inventing new ones.
+8. Keep controllers thin.
+9. Keep persistence code out of Razor views and controllers.
+10. Keep external provider response types inside Infrastructure.
+11. Add tests for business rules and bug fixes.
+12. Run build/tests after meaningful changes.
+13. Do not silently change database semantics.
+14. Create migrations for schema changes; never hand-edit production schema.
+15. Never fabricate retailer capabilities or data.
 14. If external data is unavailable, represent it as unavailable/stale—not guessed.
-16. Preserve backward-compatible URLs where practical once routes ship.
-17. Use comments for why, not obvious what.
-18. Prefer clear conventional C# over clever abstraction.
+17. Preserve backward-compatible URLs where practical once routes ship.
+18. Use comments for why, not obvious what.
+19. Prefer clear conventional C# over clever abstraction.
 
 ---
 

CLAUDE.md

@@ -12,6 +12,14 @@ Read these files before making substantial changes:
 
 Use `docs/scrum-backlog.md` as the shared execution tracker. Do not keep meaningful implementation progress only in chat.
 
+Prompt workflow guidance lives in `docs/prompt-process.md`.
+
+If a substantial user prompt does not follow the standard prompt pattern, the agent should:
+- infer the likely request and continue helping
+- briefly show a corrected prompt in the recommended format
+- use the corrected structure for the work going forward
+- avoid refusing the task solely because the prompt was informal
+
 ---
 
 ## Current Delivery Context
@@ -136,6 +144,25 @@ Keep dependency direction clean.
 
 ---
 
+## Prompt Workflow
+
+For substantial work, prefer the standard prompt format defined in `docs/prompt-process.md`.
+
+Expected prompt fields:
+- `Work Type`
+- `Backlog Item`
+- `Goal`
+- `Why`
+- `Scope`
+- `Out of Scope`
+- `Constraints`
+- `Definition of Done`
+- `Deliverables`
+
+If the prompt is incomplete, repair it by showing a recommended version and then proceed with the work using the repaired structure.
+
+---
+
 ## Backlog Workflow
 
 Before implementation work:

docs/prompt-process.md

@@ -0,0 +1,189 @@
+# CartWise Prompt Process
+
+## Purpose
+
+This document defines the standard prompt format and working process for CartWise so a solo founder + AI workflow stays aligned with Agile and Scrum practices without adding unnecessary overhead.
+
+Use this process for:
+- story implementation
+- bug fixing
+- refactoring
+- backlog or plan changes
+- research spikes
+- reviews
+- MVP release checks
+
+## Core Rule
+
+Every substantial prompt should tell the agent:
+1. what type of work this is
+2. what backlog item it belongs to
+3. what outcome is required
+4. what is in and out of scope
+5. what constraints apply
+6. how completion will be judged
+7. what docs must be updated
+
+## Standard Prompt Template
+
+Use this template for most work:
+
+```text
+Work Type: [Story | Bug | Refactor | Plan Change | Spike | Review | Release]
+Backlog Item: [ID or untracked]
+Goal: [specific outcome]
+Why: [business or user reason]
+Scope: [what is in scope]
+Out of Scope: [what is not allowed]
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, and docs/release-mvp-checklist.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: [testable finish line]
+Deliverables: [code, tests, docs, backlog updates, decision log updates, or review summary]
+If you discover scope, architecture, or release-plan impacts, update the relevant docs before finishing.
+```
+
+## Accepted Work Types
+
+Use one of these values for `Work Type`:
+- `Story`
+- `Bug`
+- `Refactor`
+- `Plan Change`
+- `Spike`
+- `Review`
+- `Release`
+
+## Prompt Expectations By Work Type
+
+### Story
+Use for implementing backlog work.
+- include the story ID
+- include acceptance-focused done criteria
+- require backlog task updates when work completes
+
+Example:
+
+```text
+Work Type: Story
+Backlog Item: CW-STORY-03.3
+Goal: Implement free-text grocery item creation on the active list
+Why: Users need to capture grocery needs without product resolution
+Scope: Add-item flow, validation, controller action, Razor form, and persistence
+Out of Scope: Barcode work, external providers, shopping mode changes
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, and docs/release-mvp-checklist.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: User can add a free-text item and see it on the list; tests updated; backlog updated
+Deliverables: Code changes, tests, and updates to docs/scrum-backlog.md
+```
+
+### Bug
+Use for defects or regressions.
+- include observed behavior
+- include expected behavior
+- request root-cause analysis when useful
+- add regression coverage when appropriate
+
+Example:
+
+```text
+Work Type: Bug
+Backlog Item: CW-STORY-03.4
+Goal: Fix list item toggle failure
+Why: Purchased items are not persisting correctly
+Scope: Reproduce, identify root cause, fix, and add regression coverage
+Out of Scope: Unrelated list refactors
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, and docs/release-mvp-checklist.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: Toggle works reliably, regression test added, backlog updated if needed
+Deliverables: Fix, tests, and short root-cause summary
+```
+
+### Refactor
+Use for code cleanup without changing intended behavior.
+- state what must remain behaviorally unchanged
+- limit scope to the targeted area
+- avoid hidden feature expansion
+
+### Plan Change
+Use for backlog, scope, sequencing, or release-plan updates.
+- require updates to `docs/scrum-backlog.md`
+- update `docs/decision-log.md` when a meaningful decision is made
+- avoid code changes unless explicitly requested
+
+Example:
+
+```text
+Work Type: Plan Change
+Backlog Item: CW-EPIC-05
+Goal: Re-scope purchase flow for MVP
+Why: Current path is too large for the September 10, 2026 MVP target
+Scope: Update backlog, mark post-MVP items, adjust dependencies
+Out of Scope: Code changes unless needed and explicitly requested
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, and docs/release-mvp-checklist.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: Backlog and decision docs clearly reflect the new plan
+Deliverables: Updates to docs/scrum-backlog.md, docs/decision-log.md, and a summary of impact
+```
+
+### Spike
+Use for research or time-boxed investigation.
+- clearly state the question to answer
+- define the expected output format
+- do not drift into implementation unless explicitly approved
+
+### Review
+Use for architecture review, code review, backlog review, or MVP readiness review.
+- ask for gaps, risks, and next steps
+- require separation of MVP blockers vs post-MVP suggestions
+
+### Release
+Use for release readiness checks.
+- review against `docs/release-mvp-checklist.md`
+- identify blockers, risks, and remaining required work
+
+## Prompt Repair Rule
+
+If a user prompt does **not** follow this pattern and the work is substantial, the agent should:
+1. make a reasonable effort to infer the request
+2. continue helping instead of refusing the task
+3. briefly show a corrected prompt in the recommended format
+4. use that corrected structure for the work going forward
+
+The goal is to coach the workflow without creating unnecessary friction.
+
+Example repair response:
+
+```text
+Recommended prompt format:
+Work Type: Story
+Backlog Item: CW-STORY-03.3
+Goal: Implement free-text grocery item creation on the active list
+Why: Users need to capture grocery needs without product resolution
+Scope: Add-item flow, validation, controller action, Razor form, and persistence
+Out of Scope: Barcode work, external providers, shopping mode changes
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, and docs/release-mvp-checklist.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: User can add a free-text item and see it on the list; tests updated; backlog updated
+Deliverables: Code changes, tests, and updates to docs/scrum-backlog.md
+```
+
+## Prompt-Scale Agile Flow
+
+For each substantial request, the agent should follow this sequence:
+1. **Understand** the work type, backlog context, and constraints
+2. **Plan** the smallest valuable slice
+3. **Execute** only the scoped work
+4. **Verify** with build, tests, or review as appropriate
+5. **Update** backlog and decision artifacts when the work changes completion state or plan
+
+## Weekly Solo Scrum Rhythm
+
+Suggested recurring prompts:
+- weekly planning: choose the next `P0` MVP story
+- daily check: identify the highest-value next action
+- bug fix: investigate and repair with regression coverage
+- plan adjustment: re-check the backlog against the MVP deadline
+- Friday review: compare progress against `docs/release-mvp-checklist.md`
+
+## Related Documents
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `docs/scrum-backlog.md`
+- `docs/decision-log.md`
+- `docs/release-mvp-checklist.md`

docs/prompts/bug-template.md

@@ -0,0 +1,30 @@
+# Bug Prompt Template
+
+Use this when fixing a defect or regression.
+
+```text
+Work Type: Bug
+Backlog Item: [story ID or untracked]
+Goal: [bug to fix]
+Why: [impact on user or delivery]
+Scope: [reproduce, isolate root cause, fix, and verify]
+Out of Scope: [unrelated refactors or feature changes]
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: [expected behavior restored and verified]
+Deliverables: [fix, tests, root-cause summary, backlog updates if needed]
+If you discover scope, architecture, or release-plan impacts, update the relevant docs before finishing.
+```
+
+## Example
+
+```text
+Work Type: Bug
+Backlog Item: CW-STORY-03.4
+Goal: Fix list item toggle failure
+Why: Purchased items are not persisting correctly
+Scope: Reproduce, identify root cause, fix, and add regression coverage
+Out of Scope: Unrelated list refactors or shopping mode changes
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: Toggle works reliably, regression test added, and backlog updated if needed
+Deliverables: Fix, tests, and short root-cause summary
+```

docs/prompts/plan-change-template.md

@@ -0,0 +1,30 @@
+# Plan Change Prompt Template
+
+Use this when changing scope, sequencing, backlog structure, or release planning.
+
+```text
+Work Type: Plan Change
+Backlog Item: [epic ID, story ID, or untracked]
+Goal: [specific planning change needed]
+Why: [deadline, complexity, blocker, dependency, or scope reason]
+Scope: [what planning artifacts should change]
+Out of Scope: [code changes unless explicitly requested]
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: [backlog and planning docs clearly reflect the updated plan]
+Deliverables: [updates to backlog, decision log, checklist, and a summary of impact]
+If you discover scope, architecture, or release-plan impacts, update the relevant docs before finishing.
+```
+
+## Example
+
+```text
+Work Type: Plan Change
+Backlog Item: CW-EPIC-05
+Goal: Re-scope purchase flow for MVP
+Why: Current implementation path is too large for the September 10, 2026 MVP target
+Scope: Update backlog, mark post-MVP items, adjust dependencies, and clarify decision gates
+Out of Scope: Code changes unless needed and explicitly requested
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: docs/scrum-backlog.md and docs/decision-log.md reflect the new plan clearly
+Deliverables: Updates to docs/scrum-backlog.md, docs/decision-log.md, and a short summary of delivery impact
+```

docs/prompts/release-review-template.md

@@ -0,0 +1,30 @@
+# Release Review Prompt Template
+
+Use this when checking MVP readiness or identifying blockers before release.
+
+```text
+Work Type: Release
+Backlog Item: MVP Release
+Goal: Review current MVP readiness
+Why: [confirm release readiness or identify blockers]
+Scope: Review the implemented work against docs/release-mvp-checklist.md and the MVP backlog
+Out of Scope: New feature implementation unless explicitly requested
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: Clear separation of complete items, blockers, risks, and next required actions
+Deliverables: Release-readiness review, blocker list, risk list, and recommended next steps
+If you discover scope, architecture, or release-plan impacts, update the relevant docs before finishing.
+```
+
+## Example
+
+```text
+Work Type: Release
+Backlog Item: MVP Release
+Goal: Review current MVP readiness for the local September 10, 2026 target
+Why: Confirm what is still required before the MVP can be considered ready
+Scope: Compare current repo state and backlog status against docs/release-mvp-checklist.md
+Out of Scope: Implementing new features during the review
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: MVP blockers, risks, completed items, and next actions are clearly identified
+Deliverables: Release-readiness summary and prioritized next steps
+```

docs/prompts/story-template.md

@@ -0,0 +1,30 @@
+# Story Prompt Template
+
+Use this when working on a backlog story implementation.
+
+```text
+Work Type: Story
+Backlog Item: CW-STORY-XX.X
+Goal: [specific outcome to implement]
+Why: [business or user reason]
+Scope: [what is in scope for this story slice]
+Out of Scope: [what must not be changed or expanded]
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: [testable finish line]
+Deliverables: [code changes, tests, docs updates, backlog updates]
+If you discover scope, architecture, or release-plan impacts, update the relevant docs before finishing.
+```
+
+## Example
+
+```text
+Work Type: Story
+Backlog Item: CW-STORY-03.3
+Goal: Implement free-text grocery item creation on the active list
+Why: Users need to capture grocery needs without product resolution
+Scope: Add-item flow, validation, controller action, Razor form, and persistence
+Out of Scope: Barcode work, external providers, shopping mode changes, and unrelated refactors
+Constraints: Follow AGENTS.md, CLAUDE.md, docs/scrum-backlog.md, docs/decision-log.md, docs/release-mvp-checklist.md, and docs/prompt-process.md. Stay within MVP unless explicitly told otherwise.
+Definition of Done: User can add a free-text item and see it on the list; relevant tests updated; backlog updated
+Deliverables: Code changes, tests, and updates to docs/scrum-backlog.md
+```