Rules and context

Project context

The skill runs in whatever project is the current workspace. Use the workspace root to resolve work/; do not assume a specific repo name or path. When recording items, consider the current project's structure and conventions so entries stay relevant.

User goals and scenarios

User goals and scenarios represent the goals or loops that users try to accomplish with the application. These are tracked to evaluate whether the app is fulfilling user needs.

Deferred vs improvements vs tech debt

• DEFERRED.md: Ideas (often AI-suggested) explicitly parked for later—not committed to the near-term backlog.
• IMPROVEMENTS.md: Product or process improvements you may want soon; still distinct from scheduled iteration work until moved.
• TECH_DEBT.md: Codebase quality and maintainability tradeoffs; different from feature todos and from defect tracking.

Important rules

• ALWAYS commit after recording a new item — The record command (improve, feedback, deferred, tech debt, feat, todo, task, bug, goal, scenario) MUST end with a git commit. Stage only the specific work/ files that changed (never git add .) and commit with the xp_work: record PREFIX-N message. The operation is NOT complete until the commit succeeds. If the commit fails, report the error — do not silently skip it. (The pluck, work-complete, done, iteration, acceptance, accept, and unpluck commands manage their own commit workflows.)
• Always read the target file first (after bootstrap) to see the current format and content
• Add new entries to the end of the file
• Maintain consistent formatting — match the style of existing entries
• Ask clarifying questions only when the correct file or a minimal title cannot be determined—do not ask to refine scope or solution
• Do NOT implement application or product changes except when running the pluck or work-complete commands end-to-end. The accept command only edits work/ACCEPTANCE.md and commits—no product code. Otherwise only record and manage tracking files.
• Get today's date using date +%Y-%m-%d or system date in YYYY-MM-DD format
• When moving sections, extract the entire section including the heading and all content
• For iteration moves, always include source information (which file the item came from)
• For acceptance moves, include both the original date and the date moved to acceptance