From 8deb6c07acb5ada43b3afce1696a8a479385cfa2 Mon Sep 17 00:00:00 2001 From: Daniel Covington Date: Mon, 10 Aug 2026 11:21:57 -0400 Subject: [PATCH] prompt guidance work --- AGENTS.md | 30 ++-- CLAUDE.md | 27 ++++ docs/prompt-process.md | 189 ++++++++++++++++++++++++ docs/prompts/bug-template.md | 30 ++++ docs/prompts/plan-change-template.md | 30 ++++ docs/prompts/release-review-template.md | 30 ++++ docs/prompts/story-template.md | 30 ++++ 7 files changed, 353 insertions(+), 13 deletions(-) create mode 100644 docs/prompt-process.md create mode 100644 docs/prompts/bug-template.md create mode 100644 docs/prompts/plan-change-template.md create mode 100644 docs/prompts/release-review-template.md create mode 100644 docs/prompts/story-template.md diff --git a/AGENTS.md b/AGENTS.md index 199cdf6..70c90ca 100644 --- a/AGENTS.md +++ b/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. --- diff --git a/CLAUDE.md b/CLAUDE.md index 3846115..81f4d2e 100644 --- a/CLAUDE.md +++ b/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: diff --git a/docs/prompt-process.md b/docs/prompt-process.md new file mode 100644 index 0000000..3ac733f --- /dev/null +++ b/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` diff --git a/docs/prompts/bug-template.md b/docs/prompts/bug-template.md new file mode 100644 index 0000000..2440bd4 --- /dev/null +++ b/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 +``` diff --git a/docs/prompts/plan-change-template.md b/docs/prompts/plan-change-template.md new file mode 100644 index 0000000..36804ce --- /dev/null +++ b/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 +``` diff --git a/docs/prompts/release-review-template.md b/docs/prompts/release-review-template.md new file mode 100644 index 0000000..0a3a7b9 --- /dev/null +++ b/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 +``` diff --git a/docs/prompts/story-template.md b/docs/prompts/story-template.md new file mode 100644 index 0000000..4dd71dc --- /dev/null +++ b/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 +```