diff --git a/app/[locale]/print/[year]/[month]/not-found.tsx b/app/[locale]/print/[year]/[month]/not-found.tsx new file mode 100644 index 0000000..4614deb --- /dev/null +++ b/app/[locale]/print/[year]/[month]/not-found.tsx @@ -0,0 +1,6 @@ +import { NotFoundPage } from '@/app/ui/NotFoundPage'; + +const PrintPageNotFound = () => +; + +export default PrintPageNotFound; \ No newline at end of file diff --git a/app/[locale]/print/[year]/[month]/page.tsx b/app/[locale]/print/[year]/[month]/page.tsx new file mode 100644 index 0000000..d8b736e --- /dev/null +++ b/app/[locale]/print/[year]/[month]/page.tsx @@ -0,0 +1,63 @@ +import { fetchBarcodeDataForPrint } from '@/app/lib/actions/printActions'; +import { notFound } from 'next/navigation'; +import { PrintPreview } from '@/app/ui/PrintPreview'; +import { getTranslations } from 'next-intl/server'; + +interface PrintPageProps { + params: { + year: string; + month: string; + locale: string; + }; +} + +export default async function PrintPage({ params }: PrintPageProps) { + const year = parseInt(params.year); + const month = parseInt(params.month); + + // Validate year and month parameters + if (isNaN(year) || isNaN(month) || month < 1 || month > 12) { + notFound(); + } + + let printData; + + try { + printData = await fetchBarcodeDataForPrint(year, month); + } catch (error) { + console.error('Error fetching print data:', error); + notFound(); + } + + // Get translations for the current locale + const t = await getTranslations("home-page.print-preview"); + const yearMonth = `${year}-${month.toString().padStart(2, '0')}`; + const translations = { + title: t("title"), + barcodesFound: t("barcodes-found"), + barcodeSingular: t("barcode-singular"), + printButton: t("print-button"), + printFooter: t("print-footer", { date: new Date().toLocaleDateString() }), + tableHeaderIndex: t("table-header-index"), + tableHeaderBillInfo: t("table-header-bill-info"), + tableHeaderBarcode: t("table-header-barcode"), + emptyStateTitle: t("empty-state-title"), + emptyStateMessage: t("empty-state-message", { yearMonth }) + }; + + // If no barcode data found, show empty state + if (!printData || printData.length === 0) { + return ( +
+
+

{translations.emptyStateTitle}

+

+ {translations.emptyStateMessage} +

+
+
+ ); + } + + return ; +} \ No newline at end of file diff --git a/app/lib/actions/locationActions.ts b/app/lib/actions/locationActions.ts index 7accab4..be3fc07 100644 --- a/app/lib/actions/locationActions.ts +++ b/app/lib/actions/locationActions.ts @@ -264,6 +264,24 @@ export const fetchAllLocations = withUser(async (user:AuthenticatedUser, year:nu }, }, }, + { + $addFields: { + _id: { $toString: "$_id" }, + bills: { + $map: { + input: "$bills", + as: "bill", + in: { + _id: { $toString: "$$bill._id" }, + name: "$$bill.name", + paid: "$$bill.paid", + payedAmount: "$$bill.payedAmount", + hasAttachment: "$$bill.hasAttachment", + }, + }, + }, + } + }, { $project: { "_id": 1, @@ -274,12 +292,7 @@ export const fetchAllLocations = withUser(async (user:AuthenticatedUser, year:nu // "yearMonth": 1, "yearMonth.year": 1, "yearMonth.month": 1, - // "bills": 1, - "bills._id": 1, - "bills.name": 1, - "bills.paid": 1, - "bills.payedAmount": 1, - "bills.hasAttachment": 1, + "bills": 1, // "bills.attachment": 0, // "bills.notes": 0, // "bills.barcodeImage": 1, diff --git a/app/lib/actions/printActions.ts b/app/lib/actions/printActions.ts new file mode 100644 index 0000000..4007e71 --- /dev/null +++ b/app/lib/actions/printActions.ts @@ -0,0 +1,64 @@ +'use server'; + +import { getDbClient } from '../dbClient'; +import { BillingLocation, Bill } from '../db-types'; +import { AuthenticatedUser } from '../types/next-auth'; +import { withUser } from '../auth'; +import { unstable_noStore as noStore } from 'next/cache'; + +export interface PrintBarcodeData { + locationName: string; + billName: string; + barcodeImage: string; + yearMonth: string; +} + +/** + * Fetches all bills with barcode images for a specific month for printing + * @param year - Year to fetch data for + * @param month - Month to fetch data for (1-12) + * @returns Array of barcode data for printing + */ +export const fetchBarcodeDataForPrint = withUser(async (user: AuthenticatedUser, year: number, month: number): Promise => { + noStore(); + + const { id: userId } = user; + const dbClient = await getDbClient(); + + const yearMonth = `${year}-${month.toString().padStart(2, '0')}`; + + // Fetch all locations for the specific month + const locations = await dbClient.collection("lokacije") + .find({ + userId, // ensure data belongs to authenticated user + "yearMonth.year": year, + "yearMonth.month": month + }) + .toArray(); + + // Extract and flatten barcode data + const printData: PrintBarcodeData[] = []; + + for (const location of locations) { + for (const bill of location.bills) { + if (bill.barcodeImage && bill.barcodeImage.trim() !== "") { + printData.push({ + locationName: location.name, + billName: bill.name, + barcodeImage: bill.barcodeImage, + yearMonth: yearMonth + }); + } + } + } + + // Sort by location name, then by bill name for consistent ordering + printData.sort((a, b) => { + if (a.locationName !== b.locationName) { + return a.locationName.localeCompare(b.locationName); + } + return a.billName.localeCompare(b.billName); + }); + + return printData; +}); \ No newline at end of file diff --git a/app/ui/MonthLocationList.tsx b/app/ui/MonthLocationList.tsx index 8555cc6..879b323 100644 --- a/app/ui/MonthLocationList.tsx +++ b/app/ui/MonthLocationList.tsx @@ -6,6 +6,7 @@ import { AddMonthButton } from "./AddMonthButton"; import { MonthCard } from "./MonthCard"; import Pagination from "./Pagination"; import { LocationCard } from "./LocationCard"; +import { PrintButton } from "./PrintButton"; import { BillingLocation, YearMonth } from "../lib/db-types"; import { useRouter, useSearchParams } from "next/navigation"; import { ToastContainer } from 'react-toastify'; @@ -83,7 +84,10 @@ export const MonthLocationList:React.FC = ({ locations.map((location, ix) => ) : null } - +
+ + +
) } diff --git a/app/ui/PrintButton.tsx b/app/ui/PrintButton.tsx new file mode 100644 index 0000000..d38a495 --- /dev/null +++ b/app/ui/PrintButton.tsx @@ -0,0 +1,32 @@ +"use client"; + +import { PrinterIcon } from '@heroicons/react/24/outline'; +import { useTranslations } from 'next-intl'; +import { YearMonth } from '../lib/db-types'; + +export interface PrintButtonProps { + yearMonth: YearMonth; +} + +export const PrintButton: React.FC = ({ yearMonth }) => { + const t = useTranslations("home-page.month-card"); + + const handlePrintClick = () => { + window.open(`/print/${yearMonth.year}/${yearMonth.month}`, '_blank'); + }; + + return ( +
+ +
+ ); +}; \ No newline at end of file diff --git a/app/ui/PrintPreview.tsx b/app/ui/PrintPreview.tsx new file mode 100644 index 0000000..c237a6d --- /dev/null +++ b/app/ui/PrintPreview.tsx @@ -0,0 +1,154 @@ +'use client'; + +import { PrintBarcodeData } from '../lib/actions/printActions'; + +export interface PrintPreviewProps { + data: PrintBarcodeData[]; + year: number; + month: number; + translations: { + title: string; + barcodesFound: string; + barcodeSingular: string; + printButton: string; + printFooter: string; + tableHeaderIndex: string; + tableHeaderBillInfo: string; + tableHeaderBarcode: string; + }; +} + +export const PrintPreview: React.FC = ({ data, year, month, translations }) => { + + return ( + <> + {/* Print-specific CSS styles */} + + +
+ {/* Header section - hidden in print */} +
+

+ {translations.title} +

+

+ {year}-{month.toString().padStart(2, '0')} β€’ {data.length} {data.length === 1 ? translations.barcodeSingular : translations.barcodesFound} +

+ +
+ + {/* Print content */} +
+ + + + + + + + + + {data.map((item, index) => ( + + + + + + ))} + +
+ {translations.tableHeaderIndex} + + {translations.tableHeaderBillInfo} + + {translations.tableHeaderBarcode} +
+ {(index + 1).toString().padStart(2, '0')} + +
+
+ πŸ“… {item.yearMonth} +
+
+ 🏠 {item.locationName} +
+
+ πŸ“‹ {item.billName} +
+
+ 		+
+ {`Barcode +
+
+ + {/* Print footer - only visible when printing */} +
+

{translations.printFooter}

+
+
+
+ + ); +}; \ No newline at end of file diff --git a/docs/framework/how-to-use-sprint-playbook-template-improved.md b/docs/framework/how-to-use-sprint-playbook-template-improved.md new file mode 100644 index 0000000..076d669 --- /dev/null +++ b/docs/framework/how-to-use-sprint-playbook-template-improved.md @@ -0,0 +1,363 @@ +# πŸ“˜ How to Use the Sprint Playbook Template (Improved) + +*(Enhanced Guide for AI Agent)* + +--- + +## 🎯 Purpose + +This enhanced guide explains how to generate a **Sprint Playbook** from the **Improved Sprint Playbook Template**. +The Playbook serves as the **single source of truth** for sprint planning, execution, and tracking. + +**AI Agent Role:** +1. Analyze user requirements with enhanced clarity checking +2. Perform comprehensive project state assessment +3. Create granular, testable user stories with dependencies +4. Populate playbook with actionable technical guidance +5. Establish quality gates and risk mitigation strategies +6. Enable iterative refinement based on user feedback + +--- + +## πŸ›  Enhanced Step-by-Step Instructions + +### 1. Analyze User Input (Enhanced) + +**MANDATORY ANALYSIS PROCESS:** +1. **Extract Primary Goal**: What is the main business/technical objective? +2. **Identify Scope Boundaries**: What is explicitly included/excluded? +3. **Parse Technical Constraints**: Frameworks, patterns, performance requirements +4. **Assess Complexity Level**: Simple (1-2 days), Medium (3-5 days), Complex (1+ weeks) +5. **Identify Integration Points**: Other systems, APIs, data sources +6. **Check for Non-Functional Requirements**: Security, performance, accessibility + +**Enhanced Clarity Checking:** +If ANY of these conditions are met, STOP and ask for clarification: + +- **Vague Success Criteria**: "improve", "enhance", "make better" without metrics +- **Missing Technical Details**: Which specific framework version, API endpoints, data formats +- **Unclear User Experience**: No mention of who uses the feature or how +- **Ambiguous Scope**: Could be interpreted as either small change or major feature +- **Conflicting Requirements**: Performance vs. feature richness, security vs. usability +- **Missing Dependencies**: References to undefined components, services, or data + +**Structured Clarification Process:** +1. **Categorize Unknowns**: Technical, Business, User Experience, Integration +2. **Ask Specific Questions**: Provide 2-3 concrete options when possible +3. **Request Examples**: "Can you show me a similar feature you like?" +4. **Validate Understanding**: Repeat back interpretation for confirmation + +--- + +### 2. Assess Current State (Comprehensive) + +**MANDATORY DISCOVERY STEPS:** +1. **Read Core Application Files**: + - Entry points: `main.py`, `index.js`, `app.py`, `src/main.ts` + - Configuration: `.env`, `config.*`, `settings.py`, `next.config.js` + - Package management: `package.json`, `requirements.txt`, `Cargo.toml`, `pom.xml` + +2. **Analyze Architecture**: + - Directory structure and organization patterns + - Module boundaries and dependency flows + - Data models and database schemas + - API endpoints and routing patterns + +3. **Review Testing Infrastructure**: + - Test frameworks and utilities available + - Current test coverage and patterns + - CI/CD pipeline configuration + - Quality gates and automation + +4. **Assess Documentation**: + - README completeness and accuracy + - API documentation status + - Code comments and inline docs + - User guides or tutorials + +5. **Identify Technical Debt**: + - Known issues or TODOs + - Deprecated dependencies + - Performance bottlenecks + - Security vulnerabilities + +**Output Requirements:** +- **Factual Assessment**: No speculation, only observable facts +- **Relevance Filtering**: Focus on sprint-related components only +- **Version Specificity**: Include exact version numbers for all dependencies +- **Gap Identification**: Clearly note missing pieces needed for sprint success + +--- + +### 3. Sprint ID Selection (Enhanced) + +**EXACT ALGORITHM:** +1. **Check Directory Structure**: + ```bash + if docs/sprints/ exists: + scan for files matching "sprint-\d\d-*.md" + else: + create directory and use "01" + ``` + +2. **Extract and Validate IDs**: + - Use regex: `sprint-(\d\d)-.*\.md` + - Validate two-digit format with zero padding + - Sort numerically (not lexicographically) + +3. **Calculate Next ID**: + - Find maximum existing ID + - Increment by 1 + - Ensure zero-padding (sprintf "%02d" format) + +4. **Conflict Resolution**: + - If gaps exist (e.g., 01, 03, 05), use next in sequence (04) + - If no pattern found, default to "01" + - Never reuse IDs even if sprint was cancelled + +**Validation Checkpoint**: Double-check calculated ID against filesystem before proceeding. + +--- + +### 4. Define Desired State (Enhanced) + +**MANDATORY SECTIONS WITH EXAMPLES:** + +1. **New Features** (Specific): + ``` + ❌ Bad: "User authentication system" + βœ… Good: "JWT-based login with Google OAuth integration, session management, and role-based access control" + ``` + +2. **Modified Features** (Before/After): + ``` + ❌ Bad: "Improve dashboard performance" + βœ… Good: "Dashboard load time: 3.2s β†’ <1.5s by implementing virtual scrolling and data pagination" + ``` + +3. **Expected Behavior Changes** (User-Visible): + ``` + ❌ Bad: "Better error handling" + βœ… Good: "Invalid form inputs show inline validation messages instead of generic alerts" + ``` + +4. **External Dependencies** (Version-Specific): + ``` + ❌ Bad: "Add React components" + βœ… Good: "Add @headlessui/react ^1.7.0 for accessible dropdown components" + ``` + +**Quality Checklist**: +- Each item is independently verifiable +- Success criteria are measurable +- Implementation approach is technically feasible +- Dependencies are explicitly listed with versions + +--- + +### 5. Break Down Into User Stories (Enhanced) + +**STORY GRANULARITY RULES:** +- **Maximum Implementation Time**: 4-6 hours of focused work +- **Independent Testability**: Each story can be tested in isolation +- **Single Responsibility**: One clear functional outcome per story +- **Atomic Commits**: Typically 1-2 commits per story maximum + +**ENHANCED STORY COMPONENTS:** + +1. **Story ID**: Sequential numbering with dependency tracking +2. **Title**: Action-oriented, 2-4 words (e.g., "Add Login Button", "Implement JWT Validation") +3. **Description**: Includes context, acceptance criteria preview, technical approach +4. **Acceptance Criteria**: 3-5 specific, testable conditions using Given/When/Then format +5. **Definition of Done**: Includes "user testing completed" for all user-facing changes +6. **Dependencies**: References to other stories that must complete first +7. **Estimated Time**: Realistic hour estimate for planning +8. **Risk Level**: Low/Medium/High based on technical complexity + +**ACCEPTANCE CRITERIA FORMAT:** +``` +Given [initial state] +When [user action or system trigger] +Then [expected outcome] +And [additional verifications] +``` + +**Example User Story:** +``` +| US-3 | Implement JWT Validation | Create middleware to validate JWT tokens on protected routes | Given a request to protected endpoint, When JWT is missing/invalid/expired, Then return 401 with specific error message, And log security event | Middleware implemented, unit tests added, error handling tested, security logging verified, **user testing completed** | AI-Agent | πŸ”² todo | 3 hours | US-1, US-2 | +``` + +**DEPENDENCY MANAGEMENT:** +- Use topological sorting for story order +- Identify critical path and potential parallelization +- Plan for dependency failures or delays +- Consider story splitting to reduce dependencies + +--- + +### 6. Add Technical Instructions (Comprehensive) + +**REQUIRED SECTIONS WITH DEPTH:** + +1. **Code Snippets/Patterns** (Executable Examples): + ```typescript + // Actual working example following project conventions + export const authenticatedRoute = withAuth(async (req: AuthRequest, res: Response) => { + const { userId } = req.user; // from JWT middleware + const data = await fetchUserData(userId); + return res.json({ success: true, data }); + }); + ``` + +2. **Architecture Guidelines** (Specific Patterns): + - **Layer Separation**: "Controllers in `/api/`, business logic in `/services/`, data access in `/repositories/`" + - **Error Handling**: "Use Result pattern, never throw in async functions" + - **State Management**: "Use Zustand for client state, React Query for server state" + +3. **Coding Style Conventions** (Tool-Specific): + - **Naming**: "Components: PascalCase, functions: camelCase, constants: SCREAMING_SNAKE_CASE" + - **Files**: "Components end with `.tsx`, utilities with `.ts`, tests with `.test.ts`" + - **Imports**: "Absolute imports with `@/` alias, group by type (libraries, internal, relative)" + +4. **Testing Strategy** (Framework-Specific): + - **Unit Tests**: "Jest + Testing Library, minimum 80% coverage for business logic" + - **Integration**: "Supertest for API endpoints, test database with cleanup" + - **Manual Testing**: "User validates UI/UX after each user-facing story completion" + +5. **Quality Gates** (Automated Checks): + - **Build**: "`npm run build` must pass without errors" + - **Lint**: "`npm run lint:check` must pass with zero warnings" + - **Format**: "`npm run prettier:check` must pass" + - **Tests**: "`npm test` must pass with coverage thresholds met" + +--- + +### 7. Capture Risks and Dependencies (Proactive) + +**ENHANCED RISK ASSESSMENT:** + +1. **Technical Risks** (with Mitigation): + ``` + Risk: "JWT library might not support RS256 algorithm" + Impact: High (blocks authentication) + Probability: Low + Mitigation: "Research jsonwebtoken vs. jose libraries in discovery phase" + ``` + +2. **Integration Risks** (with Fallbacks): + ``` + Risk: "Google OAuth API rate limits during development" + Impact: Medium (slows testing) + Probability: Medium + Fallback: "Mock OAuth responses for local development" + ``` + +3. **Timeline Risks** (with Buffers): + ``` + Risk: "Database migration complexity unknown" + Impact: High (affects multiple stories) + Buffer: "Add 20% time buffer, prepare manual migration scripts" + ``` + +**DEPENDENCY TRACKING:** +- **Internal Dependencies**: Other modules, shared utilities, database changes +- **External Dependencies**: Third-party APIs, service availability, credentials +- **Human Dependencies**: Design assets, content, domain expertise +- **Infrastructure Dependencies**: Deployment access, environment variables, certificates + +--- + +### 8. Enhanced Quality Gates + +**CODE QUALITY GATES:** +- [ ] **Static Analysis**: ESLint, SonarQube, or equivalent passes +- [ ] **Security Scan**: No high/critical vulnerabilities in dependencies +- [ ] **Performance**: No significant regression in key metrics +- [ ] **Accessibility**: WCAG compliance for user-facing changes + +**TESTING QUALITY GATES:** +- [ ] **Coverage Threshold**: Minimum X% line coverage maintained +- [ ] **Test Quality**: No skipped tests, meaningful assertions +- [ ] **Edge Cases**: Error conditions and boundary values tested +- [ ] **User Acceptance**: Manual testing completed and approved + +**DOCUMENTATION QUALITY GATES:** +- [ ] **API Changes**: OpenAPI spec updated for backend changes +- [ ] **User Impact**: User-facing changes documented in appropriate format +- [ ] **Technical Decisions**: ADRs (Architecture Decision Records) updated for significant changes +- [ ] **Runbook Updates**: Deployment or operational procedures updated + +--- + +### 9. Advanced Definition of Done (DoD) + +**AI-RESPONSIBLE ITEMS** (Comprehensive): +* [ ] All user stories meet individual DoD criteria +* [ ] All quality gates passed (code, testing, documentation) +* [ ] Code compiles and passes all automated tests +* [ ] Security review completed (dependency scan, code analysis) +* [ ] Performance benchmarks meet requirements +* [ ] Accessibility standards met (if applicable) +* [ ] Code is committed with conventional commit messages +* [ ] Branch pushed with all commits and proper history +* [ ] Documentation updated and reviewed +* [ ] Sprint status updated to `βœ… completed` +* [ ] Technical debt documented for future sprints +* [ ] Lessons learned captured in playbook + +**USER-ONLY ITEMS** (Clear Boundaries): +* [ ] User acceptance testing completed successfully +* [ ] Cross-browser/device compatibility verified +* [ ] Production deployment completed and verified +* [ ] External system integrations tested end-to-end +* [ ] Performance validated in production environment +* [ ] Stakeholder sign-off received +* [ ] User training/documentation reviewed (if applicable) +* [ ] Monitoring and alerting configured (if applicable) + +--- + +## ⚠️ Enhanced Guardrails + +**SCOPE CREEP PREVENTION:** +- Document any "nice-to-have" features discovered during implementation +- Create follow-up sprint candidates for scope additions +- Maintain strict focus on original sprint goal +- Get explicit approval for any requirement changes + +**TECHNICAL DEBT MANAGEMENT:** +- Document shortcuts taken with rationale +- Estimate effort to address debt properly +- Prioritize debt that affects sprint success +- Plan debt paydown in future sprints + +**COMMUNICATION PROTOCOLS:** +- **Daily Updates**: Progress, blockers, timeline risks +- **Weekly Reviews**: Demo working features, gather feedback +- **Blocker Escalation**: Immediate notification with context and options +- **Scope Questions**: Present options with pros/cons, request decision + +--- + +## βœ… Enhanced Output Requirements + +**MANDATORY CHECKLIST** - Sprint Playbook must have: + +1. βœ… **Validated Sprint ID** - Following algorithmic ID selection +2. βœ… **Complete metadata** - All fields filled with realistic estimates +3. βœ… **Comprehensive state analysis** - Based on thorough code examination +4. βœ… **Measurable desired state** - Specific success criteria, not vague goals +5. βœ… **Granular user stories** - 4-6 hour implementation chunks with dependencies +6. βœ… **Executable acceptance criteria** - Given/When/Then format where appropriate +7. βœ… **Comprehensive DoD items** - Including user testing checkpoints +8. βœ… **Detailed technical guidance** - Working code examples and specific tools +9. βœ… **Proactive risk management** - Risks with mitigation strategies +10. βœ… **Quality gates defined** - Automated and manual verification steps +11. βœ… **Clear responsibility boundaries** - AI vs User tasks explicitly separated +12. βœ… **Communication protocols** - How and when to interact during sprint + +**FINAL VALIDATION**: The completed playbook should enable a different AI agent to execute the sprint successfully with minimal additional clarification. + +**ITERATIVE IMPROVEMENT**: After each sprint, capture lessons learned and refine the process for better efficiency and quality in future sprints. + +--- \ No newline at end of file diff --git a/docs/framework/how-to-use-sprint-playbook-template.md b/docs/framework/how-to-use-sprint-playbook-template.md new file mode 100644 index 0000000..5fef372 --- /dev/null +++ b/docs/framework/how-to-use-sprint-playbook-template.md @@ -0,0 +1,209 @@ +# πŸ“˜ How to Use the Sprint Playbook Template + +*(Guide for AI Agent)* + +--- + +## 🎯 Purpose + +This guide explains how to generate a **Sprint Playbook** from the **Sprint Playbook Template**. +The Playbook is the **authoritative plan and tracking file** for the Sprint. +Your role as AI agent is to: + +1. Interpret the user’s Sprint goal. +2. Analyze the current project state. +3. Split work into clear user stories. +4. Populate the Playbook with concise, actionable details. +5. Ensure the Playbook defines a **minimal implementation** β€” no extra features beyond scope. + +--- + +## πŸ›  Step-by-Step Instructions + +### 1. Analyze User Input + +* Read the user’s description of what should be achieved in the Sprint. +* Extract the **general goal** (e.g., β€œadd authentication,” β€œimprove reporting,” β€œfix performance issues”). +* Note any explicit **constraints** (frameworks, coding styles, patterns). + +**If gaps, ambiguities, or contradictions are detected:** + +**MANDATORY PROCESS:** +1. **STOP playbook creation immediately** +2. **Ask user for specific clarification** with concrete questions: + * *"Do you want authentication for all users or just admins?"* + * *"Should performance improvements target backend response times or frontend rendering?"* + * *"You mentioned using Django, but the codebase uses Flask β€” should we migrate or stick with Flask?"* +3. **Wait for user response** - do not proceed with assumptions +4. **Repeat clarification cycle** until goal is completely unambiguous +5. **Only then proceed** to create the playbook + +**CRITICAL RULE**: Never proceed with unclear requirements - this will cause blocking during implementation. + +--- + +### 2. Assess Current State + +**MANDATORY STEPS:** +1. Read project entry points (e.g., `main.py`, `index.js`, `app.py`) +2. Identify and read core business logic modules +3. Read configuration files (`.env`, `config.*`, etc.) +4. Read dependency files (`package.json`, `requirements.txt`, `Cargo.toml`, etc.) +5. List current main features available +6. List known limitations or issues +7. List relevant file paths +8. Document runtime versions, frameworks, and libraries + +**Output Requirements:** +* Keep descriptions factual and concise (2-3 sentences per item) +* Focus only on functionality relevant to the sprint goal +* Do not speculate about future capabilities + +--- + +### 3. Sprint ID Selection (Mandatory Process) + +**EXACT STEPS TO FOLLOW:** +1. **Check if `docs/sprints/` directory exists** + - If directory doesn't exist: set **Sprint ID = `01`** + - If directory exists: proceed to step 2 + +2. **List existing sprint files** + - Search for files matching pattern: `docs/sprints/sprint-??-*.md` + - Extract only the two-digit numbers (ignore everything else) + - Example: `sprint-03-auth.md` β†’ extract `03` + +3. **Calculate new ID** + - If no matching files found: set **Sprint ID = `01`** + - If files found: find maximum ID number and increment by 1 + - Preserve zero-padding (e.g., `03` β†’ `04`, `09` β†’ `10`) + +**CRITICAL RULES:** +- NEVER use IDs from example documents - examples are for formatting only +- NEVER guess or assume sprint IDs +- ALWAYS preserve two-digit zero-padding format +- This is the single source of truth for Sprint ID assignment + +--- + +### 4. Define Desired State + +**MANDATORY SECTIONS:** +1. **New Features** - List exactly what new functionality will be added +2. **Modified Features** - List existing features that will be changed +3. **Expected Behavior Changes** - Describe how user/system behavior will differ +4. **External Dependencies/Integrations** - List new libraries, APIs, or services needed + +**Requirements:** +* Each item must be specific and measurable +* Avoid vague terms like "improve" or "enhance" - be precise +* Only include changes directly needed for the sprint goal + +--- + +### 5. Break Down Into User Stories + +**STORY CREATION RULES:** +1. Each story must be implementable independently +2. Story should require 1-2 commits maximum +3. Story must have measurable acceptance criteria +4. Story must include specific DoD items + +**MANDATORY STORY COMPONENTS:** +* **Story ID**: Sequential numbering (`US-1`, `US-2`, `US-3`...) +* **Title**: 2-4 word description of the functionality +* **Description**: Clear explanation of what needs to be implemented +* **Acceptance Criteria**: Specific, testable conditions that must be met +* **Definition of Done**: Concrete checklist (implemented, tested, docs updated, lint clean) +* **Assignee**: Always `AI-Agent` for AI-implemented sprints +* **Status**: Always starts as `πŸ”² todo` + +**STATUS PROGRESSION (AI must follow exactly):** +* `πŸ”² todo` β†’ `🚧 in progress` β†’ `βœ… done` +* If blocked: any status β†’ `🚫 blocked` (requires user intervention) +* **CRITICAL**: If ANY story becomes `🚫 blocked`, STOP all sprint work immediately + +--- + +### 6. Add Technical Instructions + +**REQUIRED SECTIONS:** +* **Code Snippets/Patterns**: Include specific code examples that show structure +* **Architecture Guidelines**: Define module boundaries, layering, design patterns +* **Coding Style Conventions**: Specify naming rules, formatting, linting requirements +* **Testing Strategy**: Define what testing is required (unit/integration, framework, coverage) + +**GUIDELINES:** +* Provide concrete examples, not abstract descriptions +* If multiple approaches exist, specify exactly which one to use +* Include specific commands for building, testing, and linting +* Reference existing project conventions where possible + +--- + +### 7. Capture Risks and Dependencies + +* List potential **risks** (technical, integration, scope-related). +* List **dependencies** (modules, libraries, APIs, data sources). + +--- + +### 8. Apply Definition of Done (DoD) + +**USER STORY DoD (for each story):** +* Must include specific, measurable items like: + * "Endpoint implemented and returns correct status codes" + * "Unit tests added with 80%+ coverage" + * "Documentation updated in README" + * "Code passes linter without errors" + +**SPRINT DoD STRUCTURE (mandatory separation):** + +**AI-Responsible Items** (AI MUST tick these when completed): +* [ ] All user stories meet their individual Definition of Done +* [ ] Code compiles and passes automated tests +* [ ] Code is committed and pushed on branch `[feature/sprint-]` +* [ ] Documentation is updated +* [ ] Sprint status updated to `βœ… done` + +**User-Only Items** (AI MUST NEVER tick these): +* [ ] Branch is merged into main +* [ ] Production deployment completed (if applicable) +* [ ] External system integrations verified (if applicable) + +**CRITICAL RULE**: AI agents must NEVER tick user-only DoD items under any circumstances. + +--- + +--- + +## ⚠️ Guardrail Against Overfitting + +If you are provided with **example Sprint Playbooks**: + +* Use them **only to understand formatting and structure**. +* Do **not** copy their technologies, libraries, or domain-specific details unless explicitly relevant. +* Always prioritize: + + 1. **Sprint Playbook Template** + 2. **User instructions** + 3. **Project state analysis** + +--- + +## βœ… Output Requirements + +**MANDATORY CHECKLIST** - Sprint Playbook must have: + +1. βœ… **Correct Sprint ID** - Follow Sprint ID selection rule (increment from existing) +2. βœ… **Complete metadata** - All fields in Sprint Metadata section filled +3. βœ… **Current state analysis** - Based on actual project file examination +4. βœ… **Specific desired state** - Measurable outcomes, not vague goals +5. βœ… **Independent user stories** - Each story can be implemented separately +6. βœ… **Testable acceptance criteria** - Each story has specific pass/fail conditions +7. βœ… **Concrete DoD items** - Specific, actionable checklist items +8. βœ… **Technical guidance** - Actual code snippets and specific instructions +9. βœ… **Risk identification** - Potential blockers and dependencies listed +10. βœ… **Proper DoD separation** - AI vs User responsibilities clearly marked + +**VALIDATION**: Before finalizing, verify that another AI agent could execute the sprint based solely on the playbook content without additional clarification. \ No newline at end of file diff --git a/docs/framework/sprint-implementation-guidelines-improved.md b/docs/framework/sprint-implementation-guidelines-improved.md new file mode 100644 index 0000000..40098d5 --- /dev/null +++ b/docs/framework/sprint-implementation-guidelines-improved.md @@ -0,0 +1,524 @@ +# πŸ“˜ Sprint Implementation Guidelines (Improved) + +These enhanced guidelines define how the AI agent must implement a Sprint based on the approved **Sprint Playbook**. +They ensure consistent execution, comprehensive testing, proactive risk management, and optimal user collaboration. + +--- + +## 0. Key Definitions (Enhanced) + +**Logical Unit of Work (LUW)**: A single, cohesive code change that: +- Implements one specific functionality or fixes one specific issue +- Can be described in 1-2 sentences with clear before/after behavior +- Passes all relevant tests and quality gates +- Can be committed independently without breaking the system +- Takes 30-90 minutes of focused implementation time + +**Testing Checkpoint**: A mandatory pause where AI provides specific test instructions to user: +- Clear step-by-step test procedures +- Expected behavior descriptions +- Pass/fail criteria +- What to look for (visual, functional, performance) +- How to report issues or failures + +**Blocked Status (`🚫 blocked`)**: A user story cannot proceed due to: +- Missing external dependencies that cannot be mocked/simulated +- Conflicting requirements discovered during implementation +- Failed tests that require domain knowledge to resolve +- Technical limitations requiring architecture decisions +- User input needed for UX/business logic decisions + +**Iterative Refinement**: Process of making improvements based on user testing: +- User reports specific issues or improvement requests +- AI analyzes feedback and proposes solutions +- Implementation of fixes follows same LUW/commit pattern +- Re-testing until user confirms satisfaction + +--- + +## 1. Enhanced Git & Version Control Rules + +### 1.1 Commit Granularity (Refined) + +**MANDATORY COMMIT PATTERNS:** +* **Feature Implementation**: One LUW per commit +* **Test Addition**: Included in same commit as feature (not separate) +* **Documentation Updates**: Included in same commit as related code changes +* **Bug Fixes**: One fix per commit with clear reproduction steps in message +* **Refactoring**: Separate commits, no functional changes mixed in + +**COMMIT QUALITY CRITERIA:** +* Build passes after each commit +* Tests pass after each commit +* No temporary/debug code included +* All related files updated (tests, docs, types) + +### 1.2 Commit Message Style (Enhanced) + +**STRICT FORMAT:** +``` +(scope): + + + +