docs: add progress log distillation guidance

This commit is contained in:
Codex
2026-06-03 14:15:53 +00:00
parent a264626472
commit 8dae177795
+47
View File
@@ -94,6 +94,53 @@ has accepted a simplified target, old assertions, public routes, feature flags,
fallbacks, or dual paths that conflict with the target should be removed in the
same plan, with the user-facing breakage and migration handling stated clearly.
## Progress Log Distillation
Use this rule when turning issue/PR activity, daily work logs, or project
management updates into an OA/project SPEC, GitHub summary, or other planning
document. The output document may contain dates and current status; this
reference records only the reusable method.
Start from the active objective, not from the commit list. Read the current
SPEC, epic, board, or target issue first, then read the relevant issue and PR
activity. For UniDesk/HWLAB/AgentRun GitHub data, use the UniDesk `gh` CLI
entry rather than native `gh` or ad hoc API scripts. When the request says
"today", state the timezone and use an exact time window in the working notes or
planning document.
Summaries must be semantic, not chronological. Group activity by capability
domain such as user workflow, cloud collaboration, device access, observability,
runtime stability, delivery infrastructure, or governance. PR numbers, issue
numbers, commits, traces, and commands are evidence, not the subject of the main
text.
Every progress update must include a goal-alignment pass:
- direct alignment: work that implements or proves a stated target capability;
- enabling alignment: platform, visibility, or tooling work required before the
target capability can be delivered;
- partial alignment: work that touches the target area but leaves a named
acceptance gap;
- no observed alignment: target areas with no current evidence.
Do not overclaim based on activity volume. A closed issue, merged PR, successful
source check, or improved trace is not enough to claim the product goal is met
unless the target acceptance artifact or live/runtime evidence exists. Missing
SPECs, boundary drafts, runtime proofs, hardware evidence, or user-entry
validation must be named explicitly as remaining gaps.
Next-stage goals must be derived from those gaps, not from generic roadmap
phrases. Prefer a short list of concrete deliverables such as a SPEC issue,
boundary document, runtime validation path, stable interface contract, or
targeted migration. The next-stage section should explain why each item is the
next step toward the active objective.
Project-specific planning documents may keep dated progress sections and source
references. Long-term reference documents must not copy those dated logs; they
should only capture the stable summarization method, authority boundaries, and
acceptance criteria. For daily commander brief style, also follow
`docs/reference/code-queue-supervision.md`.
## Short-Term Work
Short-term work is the work that improves the current usable system quickly.