CartWise/docs/prompt-process.md

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:

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:

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:

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:

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:

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