full_git_analysis_prompt.md

gistfile1.txt

Current feature/project:  
**Automated Daily Change Analysis and AI-Powered Summaries for GitHub Repositories in Dev-observer**

This request is part of the following context from the PRD:  
Dev-observer will provide automated, daily AI-powered natural language summaries of recent changes (merged pull requests and commits) for enrolled GitHub repositories. Users can enroll/unenroll repositories via UI or API, and view change summaries in a timeline feed or via REST API. The system must ensure robust error handling, access control, and analytics instrumentation.

---

### Goals

- Allow users to enroll/unenroll repositories for daily change analysis via UI and API.
- Automatically analyze enrolled repositories daily, generating AI-powered summaries of merged PRs and commits.
- Store analysis job metadata and summary content for efficient querying and history.
- Expose summaries via REST API and display them in a UI timeline feed, with filtering and access control.
- Provide robust error handling, user feedback, and analytics for all core flows.

---

### Acceptance Criteria

- Users can enroll/unenroll repositories for change analysis via UI and API; enrollment status is stored in the repository protobuf JSON details.
- Daily background jobs analyze all enrolled repositories, persisting job metadata in the `repo_change_analysis` table.
- AI-generated summaries (using Langgraph/Langchain) are stored as a new observation type via the observations API.
- REST API endpoints return summaries in proto-JSON, supporting filtering by repository, date range, and status, with proper access control.
- UI displays summaries in a timeline feed, grouped by repository and date, with filtering/search and clear error/empty states.
- All errors (enrollment, analysis, summary generation, API access) are logged, persisted, and surfaced to users with retry/contact support options.
- Analytics events are logged for enrollment, summary generation, and user access.
- Automated tests cover enrollment, analysis, summary generation, API access, and error scenarios.

---

### Technical Details

#### 1. Repository Enrollment for Change Analysis

- **Storage**:  
  - Store enrollment status and config in the repository's protobuf JSON details field (no new table for enrollment).
- **API/UI**:  
  - Implement endpoints and UI controls for enrolling/unenrolling repositories.
  - Prevent duplicate enrollments; only users with repository access can modify enrollment.
  - On repository deletion or access revocation, automatically remove enrollment.
  - Log all enrollment/unenrollment actions for analytics.
- **Access Control**:  
  - Enforce authentication and repository access checks for all enrollment actions.
- **Edge Cases**:  
  - Return clear errors for duplicate enrollments, backend failures, or unauthorized actions.

#### 2. Scheduled Daily Change Analysis Job

- **Scheduler**:  
  - Implement a Python background thread-based scheduler to trigger daily analysis for all enrolled repositories.
  - Enforce concurrency limits to avoid resource exhaustion.
  - Skip jobs for unenrolled or deleted repositories.
  - Retry transient failures with backoff; persist error status on repeated failure.
  - Prevent duplicate jobs for the same repository/day.
- **Job Metadata**:  
  - Persist each job's metadata in the new `repo_change_analysis` table:
    - `id` (UUID, PK)
    - `repo_id` (UUID, FK)
    - `status` (pending/completed/failed)
    - `observation_key` (text, references observation)
    - `error_message` (text)
    - `analyzed_at`, `created_at`, `updated_at` (timestamps)
  - Index `repo_id`, `status`, `analyzed_at` for efficient queries.

#### 3. AI-Powered Change Summary Generation

- **Summarization**:  
  - Use Langgraph/Langchain to generate a natural language summary for each analysis job.
  - Summaries must focus on merged PRs and all commits since the last analysis.
  - If no changes, generate a "no significant changes" summary.
  - If AI returns incomplete/empty, store a fallback message.
- **Storage**:  
  - Store the summary as a new observation type via the observations API.
  - Link the observation key in the `repo_change_analysis` record.
- **Error Handling**:  
  - Log and persist errors in the analysis metadata.
  - If observation storage fails, persist and surface error for retry.

#### 4. Change Summary API Access

- **Endpoints**:  
  - Implement REST API endpoints to return change summaries in proto-JSON for enrolled repositories.
  - Support filtering by repository, date range, and status.
  - Return pending status if summary not yet available; clear error if repo not enrolled.
  - Enforce authentication and repository access control.
  - Return appropriate error codes/messages for unauthorized or invalid requests.
  - Revoke access if user loses repository access.

#### 5. UI Timeline Feed for Change Summaries

- **Display**:  
  - Show summaries in a chronological timeline, grouped by repository and date.
  - Allow filtering/search by repository and date range.
  - Only show summaries to users with repository access.
  - Clearly indicate error states (failed analysis), with retry/contact support options.
  - Show informative empty state if no summaries.
  - Hide summaries if user loses repository access.
- **Integration**:  
  - Fetch summaries via the new REST API endpoints.
  - Use existing authentication/session context for access control.

#### 6. Change Analysis Error Handling & QA

- **Logging**:  
  - Log all analysis failures with detailed error messages in `repo_change_analysis`.
  - Use fallback logging if primary logging fails.
- **User Feedback**:  
  - Notify users of failures in the UI, with retry/contact support options.
- **Analytics**:  
  - Log analytics events for enrollment, summary generation, user access, and errors.
  - Provide error analytics for monitoring failure rates/causes.
- **Testing**:  
  - Automated tests must cover:
    - Enrollment/unenrollment (UI/API)
    - Scheduled analysis jobs (success/failure)
    - AI summary generation (normal/edge/error cases)
    - API access (auth, filtering, error states)
    - UI display (timeline, error/empty states)
    - Error handling and logging

#### 7. Architecture/Module Changes

- **Backend (Python)**:
  - Extend repository model/logic to handle enrollment status in protobuf JSON details.
  - Add/modify background scheduler for daily analysis jobs.
  - Implement/extend `repo_change_analysis` table and ORM model.
  - Integrate Langgraph/Langchain for AI summarization.
  - Extend observations API for new summary observation type.
  - Add REST API endpoints for summary access and enrollment management.
  - Implement robust error handling and logging throughout.
- **Frontend (React/TypeScript)**:
  - Add UI controls for enrollment/unenrollment (repository settings or similar).
  - Implement timeline feed for summaries, with filtering/search and error/empty states.
  - Integrate with new REST API endpoints for fetching summaries and managing enrollment.
  - Surface errors and retry/contact support options in the UI.
- **Database**:
  - Add `repo_change_analysis` table as specified (see schema above).
  - Add indexes on `repo_id`, `status`, `analyzed_at`.

#### 8. Interfaces and Types

- **Repository protobuf JSON details**:  
  - Add fields for `change_analysis_enrolled` (bool) and related config.
- **repo_change_analysis ORM model**:  
  - As per schema above.
- **Observation type**:  
  - New type for change summary, compatible with observations API.
- **API request/response types**:  
  - For enrollment, summary retrieval, filtering, and error states.

#### 9. Integration Points

- **Observations API**:  
  - Store and retrieve summary content.
- **Langgraph/Langchain**:  
  - AI summarization pipeline.
- **Authentication/Access Control**:  
  - Enforce on all relevant endpoints and UI.
- **Analytics/Logging**:  
  - Log key events and errors for monitoring and metrics.

#### 10. Side Effects/Dependencies

- UI updates for enrollment controls and timeline feed.
- Backend dependencies on Langgraph/Langchain, observations API, and scheduler.
- Database migration for new table and indexes.
- Analytics event logging for all core flows.

#### 11. Examples/Conventions

- Follow existing patterns for protobuf JSON details, observations API, and REST endpoint design.
- Use established error handling/logging conventions.
- UI should match existing design system and UX conventions.

#### 12. Testing

- Include automated tests for all critical paths and edge cases as described above.
- Focus on enrollment, analysis, summary generation, API access, UI display, and error handling.
- Do not over-engineer; align with existing testing approach.

---

**Implement all features as described above, ensuring robust integration, error handling, and analytics. Do not introduce new features or architectural changes beyond what is specified.**