# 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`