65 lines
4.3 KiB
Markdown
65 lines
4.3 KiB
Markdown
# the adopted project Failure and Documentation Operations
|
|
|
|
Load this reference when repairing a failure or changing Delivery-owned project documentation.
|
|
|
|
## Failure-Repair Workflow
|
|
|
|
When a build or CI failure is observed:
|
|
|
|
1. verify repository, linked branch and PR, exact failed command/file/test/job, failure class, and exact logs;
|
|
2. reproduce locally when feasible;
|
|
3. determine root cause before editing;
|
|
4. compare the intended fix against approved FR/NFRs, ADRs, architecture documentation, and project conventions;
|
|
5. implement the smallest safe fix;
|
|
6. add/update tests where behavior changed;
|
|
7. run local validation;
|
|
8. commit and push through the approved branch workflow;
|
|
9. inspect CI for the exact new head SHA;
|
|
10. report evidence and remaining risk;
|
|
11. repeat diagnosis, repair, and affected validation until the active gate passes.
|
|
|
|
The skill must continue with a safe forward fix when the failure and expected behavior are clear. A repairable failure does not end the Task or authorize moving to another gate or Task. If evidence is insufficient, requirements/architecture conflict, an external dependency is unavailable, or the required action exceeds authority, keep the Task in the same gate, record the separate blocker with evidence and owner, and raise the issue in the relevant channel:
|
|
|
|
- requirement/product ambiguity → `general` and/or `architecture` as appropriate;
|
|
- architecture contradiction → `architecture`;
|
|
- release policy/readiness ambiguity → `releases`;
|
|
- implementation-only blocker → `delivery`.
|
|
|
|
Never guess the team's intended direction, weaken a gate, or treat a blocker as a passed gate. Resume the same gate and continue the repair loop when the blocker is removed.
|
|
|
|
## Documentation Ownership
|
|
|
|
Maintain two documentation areas.
|
|
|
|
### Ways of Working — five sections
|
|
|
|
1. **Delivery workflow** — intake, prioritization, implementation states, and definition of done.
|
|
2. **Branching and reviews** — branch conventions, pull requests, approvals, and merge expectations.
|
|
3. **Planning and ownership** — backlog, sequencing, owners, dependencies, blockers, and escalation.
|
|
4. **Quality practices** — review standards, test strategy, defect handling, and evidence expectations.
|
|
5. **Collaboration and decisions** — channel routing, handoffs, decision references, and communication norms.
|
|
|
|
### Engineering — five sections
|
|
|
|
1. **Repository and workspace** — monorepo/application/package structure and local prerequisites.
|
|
2. **Development and testing** — commands, unit/integration testing, fixtures, and debugging.
|
|
3. **Build and continuous integration** — pipelines, checks, artifacts, runners, and failure diagnosis.
|
|
4. **Packaging and deployment preparation** — containers, Helm/GitOps interfaces, configuration, and release inputs.
|
|
5. **Operations and troubleshooting** — observability, known failure modes, recovery checks, and evidence collection.
|
|
|
|
Update these pages from verified project practice. Do not document a planned process as already operational.
|
|
|
|
## Synchronization Workflow
|
|
|
|
When planning documentation, Architecture structure, or Kanban state changes while implementation remains gated, follow [`planning-artifact-reconciliation.md`](planning-artifact-reconciliation.md). It defines fresh remote-head discovery, exact-merge-SHA validation, `READY_FOR_DELIVERY` handoff interpretation, evidence boundaries, and duplicate-status suppression.
|
|
|
|
1. Read new same-project activity and enough delivery history to avoid duplicates.
|
|
2. Before claiming new task work, verify exact-item `Approved for Implementation` evidence, exact Task `READY_FOR_DELIVERY` state, task dependencies, approved UI/UX handoff when applicable, and target version.
|
|
3. Identify executable tasks, CI failures, blockers, requirements/ADR implications, and documentation drift.
|
|
4. Load all applicable project engineering skills.
|
|
5. Complete at least one useful safe activity when an authorized path exists; otherwise document and route the exact blocker.
|
|
6. Escalate uncertainty or contradiction rather than selecting direction.
|
|
7. Verify local and remote results and update task/Feature progress in project documentation.
|
|
8. Maintain Ways of Working and Engineering pages when durable practice changed.
|
|
9. Post a concise update with work completed, evidence, blockers, and required decisions.
|