[wip] Add lean tier-2 component documentation for Sippy

[stbenjam]

Summary

• Adds AI-optimized tier-2 component documentation under ai-docs/
• Replaces APM-generated AGENTS.md with a navigation-focused entry point (94 lines)
• Documents Sippy's CI analysis domain model (jobs, tests, variants, releases, component readiness), architecture, and development workflows
• Includes 3 component-specific ADRs (BigQuery data source, PostgreSQL views, variant extraction)
• Links to Tier 1 platform docs for generic patterns (no duplication)

Generated using the agentic-docs component skill from ai-helpers.

Total: 17 files, ~1,700 lines (component-specific only)

Test plan

• Review AGENTS.md for accurate navigation structure
• Review domain concepts (ai-docs/domain/) for accuracy against actual codebase
• Review architecture doc (ai-docs/architecture/components.md) for correctness
• Verify ADRs reflect actual architectural decisions
• Verify ai-docs/references/ecosystem.md Tier 1 links are valid
• Confirm no duplication of generic platform patterns

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Added comprehensive development and testing guides with setup instructions, workflows, and debugging tips.
• Added architectural documentation detailing system design, components, and data flow.
• Added decision records documenting key design decisions and their rationale.
• Added domain concepts documentation explaining core entities and their relationships.
• Added ecosystem references for development resources and patterns.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: automatic mode

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: stbenjam

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [stbenjam]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

This PR adds comprehensive documentation for the Sippy project, establishing development workflows, testing practices, system architecture, architectural decision records (ADRs), domain concepts, and ecosystem references across 16 new markdown files in the ai-docs/ directory. No code, API declarations, or executable logic were modified.

Changes

Comprehensive Documentation Suite

Layer / File(s)	Summary
Development & Testing Workflows ai-docs/SIPPY_DEVELOPMENT.md, ai-docs/SIPPY_TESTING.md	Development guide covers prerequisites, devcontainer setup, repository structure, build commands, and workflows for backend/frontend/full-stack development. Testing guide details test organization across Go unit tests, Jest tests, and E2E tests with running commands, environment setup, and debugging guidance.
System Architecture & Design Overview ai-docs/architecture/components.md	Describes three-tier architecture (Frontend, Backend API, Data stores), repository structure, backend components (HTTP API server, data loader, variant registry, component readiness, database and cache layers), frontend architecture, and read/write data paths.
Architectural Decision Records ai-docs/decisions/adr-template.md, ai-docs/decisions/index.md, ai-docs/decisions/adr-0001-bigquery-data-source.md, ai-docs/decisions/adr-0002-component-readiness-views.md, ai-docs/decisions/adr-0003-variant-extraction.md	Establishes ADR framework and lifecycle. ADR-0001 documents BigQuery as primary data source with PostgreSQL secondary storage. ADR-0002 specifies PostgreSQL materialized views for component readiness refreshed daily. ADR-0003 describes regex-based variant extraction stored as JSONB in PostgreSQL.
Domain Concepts ai-docs/domain/index.md, ai-docs/domain/job.md, ai-docs/domain/test.md, ai-docs/domain/variant.md, ai-docs/domain/release.md, ai-docs/domain/component-readiness.md	Documents core domain entities: Job (Prow job execution), Test (CI test result), Variant (NURP\+ model for job characteristics), Release (OpenShift version), and Component Readiness (health metrics). Includes type definitions, data sources, APIs, database schemas, and relationships.
Execution Plans & Ecosystem References ai-docs/exec-plans/README.md, ai-docs/references/ecosystem.md	Execution plans overview with templates and workflow guidance. Ecosystem reference aggregates Tier 1 practices (Testing, Security, Development, Reliability) and Sippy-specific patterns for Go, database, and frontend development.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Sql Injection Prevention	❌ Error	SQL query examples in documentation use hardcoded values instead of placeholders, violating SQL injection prevention. Examples: '4.16', 'Failure', 'Failed' in WHERE clauses without parameterization.	Replace hardcoded values with placeholders (?) in all SQL examples. Update job.md, test.md, release.md, and ADR-0003. Add guidance on parameterization and prepared statements for consistency.

✅ Passed checks (16 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[wip] Add lean tier-2 component documentation for Sippy' accurately describes the main change: adding documentation files to the ai-docs/ directory for the Sippy project.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Go Error Handling	✅ Passed	PR contains only documentation additions (16 markdown files in ai-docs/). No Go code changes are present. Go error handling check is not applicable to documentation-only PRs.
Excessive Css In React Should Use Styles	✅ Passed	PR contains only 16 markdown documentation files. The custom check targets React component CSS styling, which is not present in this documentation-only PR. Check is not applicable.
Test Coverage For New Features	✅ Passed	PR contains only documentation (16 markdown files). No new code, functions, or components added. Documentation changes fall under stated exceptions.
Single Responsibility And Clear Naming	✅ Passed	Naming is specific and focused. Single-purpose directories. No generic naming patterns. Each document focuses on one concept.
Stable And Deterministic Test Names	✅ Passed	This PR adds only documentation files (.md). No Ginkgo test code or test modifications present. Custom check for test names does not apply to documentation.
Test Structure And Quality	✅ Passed	This PR adds only documentation (Markdown files) to ai-docs/. No Ginkgo test code, Go test files, or any code changes are included. The custom check for Ginkgo test quality is not applicable.
Microshift Test Compatibility	✅ Passed	This PR adds only documentation (16 markdown files). No new Ginkgo e2e tests or any Go code files are added. The MicroShift Test Compatibility check is not applicable.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	Not applicable: This PR adds only documentation files (Markdown) under ai-docs/. No new Ginkgo e2e tests are introduced, so the SNO compatibility check does not apply.
Topology-Aware Scheduling Compatibility	✅ Passed	This PR adds only markdown documentation (16 .md files). The custom check applies to deployment manifests, operator code, or controllers. No such files are present in this PR.
Ote Binary Stdout Contract	✅ Passed	PR contains only documentation changes (17 markdown files). OTE Binary Stdout Contract check applies to code-level violations. No code files were modified, so the check is not applicable.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	No Ginkgo e2e tests are added. This PR adds 16 markdown documentation files under ai-docs/. The check applies only to new Ginkgo test code, which is not present here.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[openshift-merge-bot]

Scheduling required tests:
/test e2e

[openshift-ci]

@stbenjam: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[openshift-ci]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.