project-discover-products-ops-dod

project-discover-products-ops-dod (Step5+6+7+11: Products + Ops + DoD + incremental maintenance)

Overview

This stage upgrades Discover from "being able to write it out" to "being governable and continuously usable":

• Products: converge the business module map to a governable number (default <= 6), providing a stable semantic anchor for the requirements stage
• Ops: fix the "can run, can verify, can roll back, can troubleshoot" entry points (high ROI)
• DoD: use gate rules to decide whether indexing checkmarks are allowed (the index checkmark only reflects facts)
• Delta Discover / stale: enable the knowledge base to be updated incrementally as code changes, without expiring quickly

Announce at the start:"I am using the project-discover-products-ops-dod skill to converge Products, establish Ops entry points, and enforce the DoD and incremental maintenance gate."

Products (business module aggregation and convergence <= 6)

Core principles

• Products is abusiness map, not a comprehensive feature list
• Prioritize clustering by "data ownership + external capabilities + organizational boundaries"
• Default target: <= 6; if convergence is impossible, you must state the reason and the governance recommendation entry point

High-signal clues for inferring Products from code (recommended order)

1. Data ownership: which components are the primary writers of which core objects (from the module page ## Data Contract）
2. External capability boundaries: which APIs are stable commitments (from the module page ## API Contract）
3. Organizational boundaries: owner/team division (from components/index.md）
4. Runtime boundaries: units that are independently deployed/SLO'd (if evidence exists)

products/index.md minimal template (navigation only)

# Products Index（业务地图：只导航）

> 建议收敛到 <= 6 个业务模块。这里不是功能清单。

| product | owner | entry | related_components | status |
|---|---|---|---|---|
| commerce | team-a | ./commerce.md | auth, order, payment | - [ ] |

products/{product}.md it is recommended to write only an "entry-level summary"

• TL;DR (business boundary in one sentence)
• Capability Catalog (CAP-001 granularity: capability name + one sentence + evidence entry point)
• Business Rules Index (rule name + one sentence + code evidence entry point)
• Domain Events (event name + one-sentence semantics + evidence entry point)

Prohibited: writing the product page as a full list of fields/full list of interfaces/detailed sequence diagrams; details point to code or module pages through evidence entry points.

Ops (runtime entry points and evidence chain)

Goal

Fix the "can run, can verify, can roll back, can troubleshoot" entry points. The Ops pageonly does entry points and key points, without repeating long operation manuals.

Recommended on-disk structure

.aidlc/project/ops/
  index.md
  runbook.md
  monitoring.md
  rollback.md

ops/index.md minimal template

# Ops Index（入口页）

## 运行入口
- 本地启动：../memory/structure.md#入口
- 环境变量/配置：<权威入口>

## 可观测入口
- Dashboard：
- Alerts：
- Logs：

## 回滚入口
- Rollback：

## Evidence Gaps（缺口清单）
- 缺口：
  - 期望补齐到的粒度：
  - 候选证据位置：
  - 影响：

DoD (Definition of Done) and gates

Project-level DoD (minimal self-check)

• Level-0's four Memory documents have "clear entry points/clear boundaries/navigable"
• The Level-1 index skeleton has been generated (components/products), and the index only navigates
• components/index.md contains a cross-module dependency relationship diagram (Mermaid, direct only)
• Each P0 module page satisfies: a module page exists + all fixed headings are complete (including ## Evidence and ## Evidence Gaps) + frontmatter metadata is complete + contract sections have authoritative entry points/invariants/evidence entry points
• Products converge to <= 6; or the reason for non-convergence and the governance recommendation entry point have been recorded

State consistency gate (SSOT, must be followed)

Single source of truth: whether a module is allowed to be checked at components/index.md is determined only by whether that module page meets the standard.

• Prerequisites for allowing - [x] for P0 modules
  • The module page exists and is navigable:.aidlc/project/components/{module}.md
  • The module page contains the fixed heading:## TL;DR、## API Contract、## Data Contract、## Evidence（证据入口）、## Evidence Gaps（缺口清单）
  • The module page frontmatter contains:change_frequency、last_verified_at、source_files
  • ## API Contract and ## Data Contract both contain:
    • Authoritative entry point (locatable)
    • 3–7 invariant summaries
    • Evidence entry points (minimum granularity at file/class/job/command level)
  • The body of the module page must not be scattered with placeholder sentences such as "to be added/not found/to be filled in after.../to be added later"; gaps can only be written into ## Evidence Gaps（缺口清单）
  • If gaps exist, they must be written into ## Evidence Gaps（缺口清单）, andmust notbe checked
• Degradation conditions for allowing - [x] for P1 modules
  • The module page exists; either API or Data may be missing, but gaps must be written in a structured way into Evidence Gaps
• P2 modules
  • Not checked by default; placeholder navigation is sufficient

Incremental Discover (Delta Discover) and stale detection (stale)

When to trigger Delta Discover

• When Merge-back is completed (introducing new ADRs/contracts/capabilities)
• When a PR involves changes to key source files of P0/P1 modules
• When a module is marked as stale (outdated)

Minimum execution scope of Delta Discover (stop-loss)

1. Identify affected modules (based on the changed file list and module page source_files）
2. Only update these modules':
   • .aidlc/project/components/{module}.md(TL;DR, contract paragraphs, invariants, Evidence/Evidence Gaps)
   • .aidlc/project/components/index.md(navigation links, dependency graph, checked status)
3. Update module page metadata:
   • last_verified_at
   • source_files(if the boundary changes)

Suggested way to write stale (persisted form not mandatory)

• The module page reflects "freshness" through last_verified_at Reflect "freshness"
• When a module is stale:
  • Do not continue writing requirements/design using "ignore expiration"
  • First do Delta Discover (minimum scope) to update key invariants and evidence entry points to a usable state

Red flag checklist

• Products is written as a feature list of dozens of modules (map becomes ineffective)
• Ops is written as a long operation manual (should only provide entry points and key points)
• Checking without looking at module page content (violates the SSOT gate)
• A stale module is still treated as authoritative input (Delta Discover should be done first)

Common mistakes

• Using placeholders such as "to be added/not found" instead of Evidence Gaps (gaps will be scattered forever)
• Doing only one full Discover and no incremental maintenance (knowledge quickly becomes outdated)