Merge pull request #8 from Oltrematica/005-smart-repo-filter

feat(005): Smart Repository Filtering with Activity Stats

Author: amargiovanni

CLAUDE.md

@@ -8,6 +8,8 @@ Auto-generated from all feature plans. Last updated: 2025-11-28
 - Python 3.9+ (per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re, datetime, statistics); optional: requests (already used in jira_client.py) (003-jira-quality-metrics)
 - Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json); optional: requests (existing pattern) (004-github-repo-selection)
 - N/A (repos.txt file is input, not storage) (004-github-repo-selection)
+- Python 3.9+ (per constitution, leveraging type hints) + Standard library (urllib, json); optional: requests (already in codebase) (005-smart-repo-filter)
+- N/A (in-memory filtering during selection) (005-smart-repo-filter)
 
 - Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re); optional: requests (001-modular-refactor)
 
@@ -39,9 +41,9 @@ python github_analyzer.py --days 7
 Python 3.9+ (as per constitution, leveraging type hints): Follow standard conventions
 
 ## Recent Changes
+- 005-smart-repo-filter: Added Python 3.9+ (per constitution, leveraging type hints) + Standard library (urllib, json); optional: requests (already in codebase)
 - 004-github-repo-selection: Added Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json); optional: requests (existing pattern)
 - 003-jira-quality-metrics: Added Python 3.9+ (per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re, datetime, statistics); optional: requests (already used in jira_client.py)
-- 002-jira-integration: Added Python 3.9+ (per constitution, leveraging type hints) + Standard library (urllib, json, csv, os, re); optional: requests
 
 
 <!-- MANUAL ADDITIONS START -->

repos.txt

@@ -1,4 +1 @@
-Oltrematica/manucloud
-Oltrematica/manucloud-app
-Oltrematica/PescaraParcheggi
-Oltrematica/tutorami
+

specs/005-smart-repo-filter/checklists/comprehensive.md

@@ -0,0 +1,161 @@
+# Comprehensive Requirements Quality Checklist
+
+**Feature**: 005-smart-repo-filter (Smart Repository Filtering)
+**Purpose**: Formal gate validation of requirements quality across API, CLI/UX, and Error Handling
+**Created**: 2025-11-29
+**Audience**: Peer Reviewer (PR Review)
+**Depth**: Formal Gate (~40 items)
+
+---
+
+## Requirement Completeness
+
+- [X] CHK001 - Are all menu options ([A], [L], [O], [S]) explicitly specified with filtering behavior? [Completeness, Spec §FR-003/004/005]
+- [X] CHK002 - Is the exact statistics display format fully specified beyond "N repos found, M with activity"? [Completeness, Spec §FR-007]
+- [X] CHK003 - Are requirements for the confirmation prompt response options (Y/n/all) documented? [Gap]
+- [X] CHK004 - Is the `pushed_at` field parsing format explicitly specified in requirements? [Completeness, Spec §FR-002]
+- [X] CHK005 - Are requirements documented for what happens when `--days` parameter is not provided? [Gap]
+- [X] CHK006 - Is the cutoff date calculation (inclusive vs exclusive of boundary day) specified? [Gap]
+
+---
+
+## Requirement Clarity
+
+- [X] CHK007 - Is "recent activity" quantified with the specific `pushed_at` field definition? [Clarity, Spec §FR-002]
+- [X] CHK008 - Is "gracefully falling back" in FR-008 defined with specific behavior steps? [Clarity, Spec §FR-008]
+- [X] CHK009 - Is the "warning" message format for zero results explicitly specified? [Clarity, Spec §FR-009]
+- [X] CHK010 - Is "within 5 seconds" in SC-001 measured from what starting point? [Ambiguity, Spec §SC-001]
+- [X] CHK011 - Is "without timeout or performance degradation" in SC-005 quantified? [Ambiguity, Spec §SC-005]
+- [X] CHK012 - Are the specific Search API query qualifiers (`org:`, `pushed:>`) documented in requirements? [Clarity]
+
+---
+
+## Requirement Consistency
+
+- [X] CHK013 - Are activity filtering requirements consistent between personal repos (FR-003) and org repos (FR-004)? [Consistency]
+- [X] CHK014 - Is the confirmation prompt pattern consistent across [A], [L], and [O] handlers? [Consistency]
+- [X] CHK015 - Are statistics display formats consistent between personal and organization repos? [Consistency, Spec §FR-007]
+- [X] CHK016 - Do plan.md method names align with tasks.md function signatures? [Consistency, Plan/Tasks]
+- [X] CHK017 - Are rate limit handling requirements consistent between Search API and REST API? [Consistency, Spec §FR-008]
+
+---
+
+## Acceptance Criteria Quality
+
+- [X] CHK018 - Can "135 repos found, 28 with activity" format be objectively verified? [Measurability, Spec §US1]
+- [X] CHK019 - Is the acceptance scenario "only repositories with recent activity are analyzed" testable? [Measurability, Spec §US1-3]
+- [X] CHK020 - Can "100% accuracy" in SC-003 be objectively measured? [Measurability, Spec §SC-003]
+- [X] CHK021 - Are independent test criteria for each user story specific enough to execute? [Measurability]
+- [X] CHK022 - Is "significant time savings" in US1/US2 quantified? [Ambiguity, Spec §US1/US2]
+
+---
+
+## Scenario Coverage - Primary Flows
+
+- [X] CHK023 - Are requirements complete for [A] option with activity filtering? [Coverage, Spec §FR-003]
+- [X] CHK024 - Are requirements complete for [L] option with numbered selection + filtering? [Coverage, Spec §FR-003]
+- [X] CHK025 - Are requirements complete for [O] option with org name input + Search API? [Coverage, Spec §FR-004]
+- [X] CHK026 - Are requirements complete for [S] option explicitly bypassing filter? [Coverage, Spec §FR-005]
+
+---
+
+## Scenario Coverage - Alternate Flows
+
+- [X] CHK027 - Are requirements defined for user selecting "all" to bypass filter? [Coverage, Spec §FR-006]
+- [X] CHK028 - Are requirements defined for user adjusting timeframe when zero results? [Coverage, Edge Case §1]
+- [X] CHK029 - Are requirements defined for re-prompting after invalid menu selection? [Gap]
+- [X] CHK030 - Is the behavior specified when user cancels during confirmation prompt? [Gap]
+
+---
+
+## Scenario Coverage - Exception/Error Flows
+
+- [X] CHK031 - Are requirements complete for Search API rate limit (403) handling? [Coverage, Spec §FR-008]
+- [X] CHK032 - Are requirements defined for Search API server errors (5xx)? [Gap, Edge Case §2]
+- [X] CHK033 - Is `incomplete_results` flag handling specified with user feedback? [Coverage, Edge Case]
+- [X] CHK034 - Are requirements defined for network timeout during Search API call? [Gap]
+- [X] CHK035 - Are requirements defined for authentication failure during search? [Gap]
+
+---
+
+## Scenario Coverage - Recovery Flows
+
+- [X] CHK036 - Is fallback-to-unfiltered-mode recovery path fully specified? [Coverage, Spec §FR-008]
+- [X] CHK037 - Can user retry with different timeframe after zero results? [Coverage, Edge Case §1]
+- [X] CHK038 - Is retry behavior specified for transient Search API failures? [Gap]
+
+---
+
+## Non-Functional Requirements - Performance
+
+- [X] CHK039 - Is the 5-second response requirement (SC-001) defined for all repo counts? [Coverage, Spec §SC-001]
+- [X] CHK040 - Are performance requirements specified for 500+ repos scenario (SC-005)? [Coverage, Spec §SC-005]
+- [X] CHK041 - Is Search API pagination performance requirement specified for large orgs? [Gap]
+- [X] CHK042 - Is memory usage requirement specified for large result sets? [Gap]
+
+---
+
+## Non-Functional Requirements - API Constraints
+
+- [X] CHK043 - Is the 30 requests/minute Search API rate limit documented in requirements? [Coverage, Assumptions]
+- [X] CHK044 - Is the 1000 results/query Search API limit documented? [Coverage, Assumptions]
+- [X] CHK045 - Are Search API vs REST API rate limit pool differences documented? [Coverage, Assumptions]
+
+---
+
+## Dependencies & Assumptions
+
+- [X] CHK046 - Is the assumption "Search API provides `pushed` date filtering" validated? [Assumption, Spec §Assumptions]
+- [X] CHK047 - Is the dependency on Feature 004's `select_github_repos()` documented? [Dependency]
+- [X] CHK048 - Is the `--days` parameter availability from existing config documented? [Dependency]
+- [X] CHK049 - Is the existing `list_org_repos()` method availability validated for T026? [Dependency]
+
+---
+
+## Ambiguities & Conflicts
+
+- [X] CHK050 - Is there a conflict between "automatic filtering" default and user expectation of seeing all repos? [Conflict]
+- [X] CHK051 - Is the term "active" vs "recently pushed" used consistently throughout? [Terminology]
+- [X] CHK052 - Is the hybrid approach (Search API for org, client-side for personal) explicitly justified in requirements? [Gap]
+
+---
+
+## Summary
+
+| Category | Items | Focus | Status |
+|----------|-------|-------|--------|
+| Requirement Completeness | CHK001-CHK006 | Missing specifications | ✅ PASS |
+| Requirement Clarity | CHK007-CHK012 | Vague/ambiguous terms | ✅ PASS |
+| Requirement Consistency | CHK013-CHK017 | Cross-artifact alignment | ✅ PASS |
+| Acceptance Criteria Quality | CHK018-CHK022 | Measurability | ✅ PASS |
+| Primary Flow Coverage | CHK023-CHK026 | Core scenarios | ✅ PASS |
+| Alternate Flow Coverage | CHK027-CHK030 | User choice paths | ✅ PASS |
+| Exception Flow Coverage | CHK031-CHK035 | Error scenarios | ✅ PASS |
+| Recovery Flow Coverage | CHK036-CHK038 | Fallback behavior | ✅ PASS |
+| Performance NFRs | CHK039-CHK042 | Speed/scale requirements | ✅ PASS |
+| API Constraints | CHK043-CHK045 | External limits | ✅ PASS |
+| Dependencies | CHK046-CHK049 | External factors | ✅ PASS |
+| Ambiguities | CHK050-CHK052 | Conflicts/terminology | ✅ PASS |
+
+**Total Items**: 52
+**Completed**: 52/52 (100%)
+**Status**: ✅ PASSED
+
+## Resolution Notes
+
+All checklist items have been addressed in the updated `spec.md`:
+
+1. **Glossary added**: Defines "active repository", "inactive repository", "cutoff date", "pushed_at", and "activity filter"
+2. **FR-002 updated**: Specifies `pushed_at` ISO 8601 format and exact filtering logic
+3. **FR-003/FR-004 updated**: Detailed behavior for each menu option
+4. **FR-006 updated**: Confirmation prompt options (Y/n/all) fully documented
+5. **FR-008 updated**: Graceful fallback steps for rate limit, server errors, and timeout
+6. **FR-010 updated**: Default behavior when --days not provided
+7. **Edge cases expanded**: 10 specific scenarios with exact error messages
+8. **SC-001 clarified**: "5 seconds" measured from user pressing Enter
+9. **SC-005 clarified**: "10 seconds" includes pagination, "without degradation" means <10s response
+10. **Performance table added**: Response time and memory limits per scenario
+11. **API Constraints section**: Documents 30 req/min, 1000 results/query, separate rate pools
+12. **Dependencies section**: Validates all internal dependencies exist
+13. **Design Decisions section**: Justifies hybrid approach and default filtering behavior
+14. **US1/US2 updated**: Quantified time savings (~80%, ~90%)

specs/005-smart-repo-filter/checklists/requirements.md

@@ -0,0 +1,51 @@
+# Requirements Checklist: Smart Repository Filtering
+
+**Feature**: 005-smart-repo-filter
+**Validated**: 2025-11-29
+
+## Specification Quality Criteria
+
+### User Stories
+- [x] At least one user story with clear acceptance scenarios
+- [x] Each story has priority (P1-P4) with justification
+- [x] Independent test scenario for each story
+- [x] Edge cases identified and documented
+
+### Functional Requirements
+- [x] Requirements use MUST/SHOULD/MAY language
+- [x] Each requirement is testable
+- [x] Requirements map to user stories
+- [x] No conflicting requirements
+
+### Success Criteria
+- [x] Measurable outcomes defined
+- [x] Criteria are objective (not subjective)
+- [x] Performance expectations specified
+
+### Technical Feasibility
+- [x] GitHub Search API endpoint documented
+- [x] Rate limit considerations addressed (FR-008)
+- [x] Fallback behavior defined
+
+## Requirement Traceability
+
+| Requirement | User Story | Testable | Notes |
+|-------------|-----------|----------|-------|
+| FR-001 | US1, US2 | Yes | Display activity stats |
+| FR-002 | US1, US2 | Yes | Filter by pushed date |
+| FR-003 | US1 | Yes | Personal repos filtering |
+| FR-004 | US2 | Yes | Org repos filtering |
+| FR-005 | US3 | Yes | No filter for manual [S] |
+| FR-006 | US3 | Yes | Disable filter option |
+| FR-007 | US1, US2 | Yes | Stats format |
+| FR-008 | Edge Case | Yes | Rate limit fallback |
+| FR-009 | Edge Case | Yes | Zero repos warning |
+| FR-010 | US1, US2 | Yes | Use --days parameter |
+
+## Validation Summary
+
+- **Total Requirements**: 10
+- **Testable Requirements**: 10/10 (100%)
+- **User Stories**: 3 (P1, P2, P3)
+- **Edge Cases**: 4 documented
+- **Status**: PASSED