docs: add progress log distillation guidance
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user