Implementation Plans

Oversight generates cohesive implementation plans from analysis observations. Plans combine multiple issues into a single actionable document with root cause analysis, architecture approach, and step-by-step implementation guidance.

How Plan Generation Works

Plan generation starts from an observation — a natural-language description of a problem or improvement area identified during analysis. The observation references one or more GitHub issues/PRs whose details are fetched automatically.

The plan generation pipeline:

1. Receives the observation text and a list of issue/PR numbers
2. Fetches full details for each referenced issue from the GitHub API (title, labels, body)
3. Sends the combined context to Claude Opus with a specialized generate-plan prompt
4. Returns a structured Markdown plan covering all referenced items cohesively
5. Optionally syncs the plan to Notion for persistence

Plan Structure

Every generated plan follows a consistent structure designed for both human review and machine execution:

Problem Summary

A concise description of the problem space, synthesized from the observation and the referenced issues. This frames the "why" before diving into solutions.

Root Cause Analysis

Identifies the underlying causes across the referenced issues. When multiple issues share a common root cause, the plan consolidates them rather than treating each in isolation.

Architecture Approach

Describes the high-level technical approach: which components are affected, what patterns to use, and how the changes fit into the existing codebase.

Implementation Steps

Ordered, granular steps that can be followed by a developer or dispatched to Claude Code for automated execution. Each step specifies which files to modify and what changes to make.

Testing Strategy

Defines what tests to write or update, including unit tests, integration tests, and any manual verification steps.

Risks and Mitigations

Identifies potential risks (breaking changes, performance regressions, edge cases) and how to mitigate them.

Multi-Issue Cohesive Plans

A key strength of plan generation is handling multiple related issues as a single unit of work. Rather than generating separate plans per issue, oversight produces one cohesive plan that addresses all of them together.

API Endpoint

Request Body

interface GeneratePlanRequest {
  repoId: number;
  observation: string;
  issueNumbers: number[];
  syncToNotion?: boolean;
}

Response

interface GeneratePlanResponse {
  taskId: string;
}

Task Lifecycle

Plan generation runs as a generate-plan task type. The task progresses through these stages:

Notion Sync

When syncToNotion is true, the completed plan is automatically posted to Notion as a page under the configured database. The plan title follows the format Implementation Plan — owner/repo. The task record stores both the notion_page_id and notion_page_url for reference.

Configuration