@longph2102/v-flow 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +265 -0
- package/CHANGELOG.md +318 -0
- package/LICENSE +21 -0
- package/README.md +326 -0
- package/agents/ba-agent.md +437 -0
- package/agents/ba-critic-agent.md +156 -0
- package/agents/ba-to-ptyc-agent.md +112 -0
- package/agents/bugfix-analyst-agent.md +221 -0
- package/agents/constitute-agent.md +155 -0
- package/agents/help-agent.md +168 -0
- package/agents/implement-agent.md +220 -0
- package/agents/import-ba-docs-agent.md +164 -0
- package/agents/master-check-agent.md +228 -0
- package/agents/metrics-agent.md +180 -0
- package/agents/operations-agent.md +123 -0
- package/agents/plan-agent.md +218 -0
- package/agents/prototype-agent.md +191 -0
- package/agents/retrospective-agent.md +196 -0
- package/agents/review-agent.md +210 -0
- package/agents/sprint-agent.md +191 -0
- package/agents/status-agent.md +186 -0
- package/agents/sync-agent.md +201 -0
- package/agents/test-agent.md +166 -0
- package/agents/understand-agent.md +339 -0
- package/cli/commands/check.js +96 -0
- package/cli/commands/dev-quiz.js +107 -0
- package/cli/commands/doctor.js +348 -0
- package/cli/commands/feature.js +259 -0
- package/cli/commands/hooks.js +163 -0
- package/cli/commands/init.js +189 -0
- package/cli/commands/log.js +199 -0
- package/cli/commands/plugin.js +230 -0
- package/cli/commands/score-card.js +203 -0
- package/cli/commands/status.js +269 -0
- package/cli/commands/sync.js +59 -0
- package/cli/commands/upgrade.js +150 -0
- package/cli/commands/validate.js +1259 -0
- package/cli/commands/watch.js +151 -0
- package/cli/index.js +46 -0
- package/cli/lib/ac-test-gate.js +89 -0
- package/cli/lib/activity-log.js +209 -0
- package/cli/lib/cli-error.js +183 -0
- package/cli/lib/constitution-lint.js +561 -0
- package/cli/lib/dev-quiz-grade.js +127 -0
- package/cli/lib/governance.js +78 -0
- package/cli/lib/hook-targets.js +167 -0
- package/cli/lib/i18n.js +375 -0
- package/cli/lib/knowledge-oracle.js +379 -0
- package/cli/lib/logger.js +203 -0
- package/cli/lib/module-card-lint.js +304 -0
- package/cli/lib/module-card-score.js +223 -0
- package/cli/lib/plugins.js +481 -0
- package/cli/lib/scanner.js +692 -0
- package/cli/lib/sync-core.js +232 -0
- package/cli/lib/sync-targets.js +84 -0
- package/cli/lib/templates.js +268 -0
- package/cli/lib/yaml-parser.js +203 -0
- package/commands/v.ba-critic.md +101 -0
- package/commands/v.ba-to-ptyc.md +71 -0
- package/commands/v.bugfix.md +86 -0
- package/commands/v.check.md +131 -0
- package/commands/v.constitute.md +87 -0
- package/commands/v.constitution.md +84 -0
- package/commands/v.fork.md +127 -0
- package/commands/v.help.md +73 -0
- package/commands/v.hotfix.md +200 -0
- package/commands/v.implement.md +92 -0
- package/commands/v.import-ba-docs.md +222 -0
- package/commands/v.metrics.md +74 -0
- package/commands/v.operations.md +70 -0
- package/commands/v.plan.md +78 -0
- package/commands/v.prototype.md +121 -0
- package/commands/v.quickfix.md +169 -0
- package/commands/v.retrospective.md +80 -0
- package/commands/v.review.md +78 -0
- package/commands/v.rewind.md +127 -0
- package/commands/v.specify.md +118 -0
- package/commands/v.sprint.md +75 -0
- package/commands/v.status.md +62 -0
- package/commands/v.sync.md +81 -0
- package/commands/v.test.md +67 -0
- package/commands/v.understand.md +112 -0
- package/package.json +65 -0
- package/skills/_shared/constitution-reader/SKILL.md +109 -0
- package/skills/_shared/constitution-reader/config.json +52 -0
- package/skills/_shared/constitution-reader/examples/good/b1-phase-output.md +48 -0
- package/skills/_shared/constitution-reader/gotchas.md +46 -0
- package/skills/_shared/context-reader/SKILL.md +111 -0
- package/skills/_shared/context-reader/config.json +54 -0
- package/skills/_shared/context-reader/examples/good/legacy-nodejs-output.md +35 -0
- package/skills/_shared/context-reader/gotchas.md +49 -0
- package/skills/_shared/ears-notation/SKILL.md +63 -0
- package/skills/_shared/ears-notation/config.json +55 -0
- package/skills/_shared/ears-notation/examples/good/plan-test-interpretation.md +29 -0
- package/skills/_shared/ears-notation/gotchas.md +43 -0
- package/skills/check/cross-validator/SKILL.md +206 -0
- package/skills/check/cross-validator/config.json +33 -0
- package/skills/check/cross-validator/examples/good/validation-report-pass-with-concerns.md +105 -0
- package/skills/check/cross-validator/gotchas.md +43 -0
- package/skills/implement/constitution-enforcer/SKILL.md +134 -0
- package/skills/implement/constitution-enforcer/config.json +16 -0
- package/skills/implement/constitution-enforcer/examples/bad/vague-report.md +42 -0
- package/skills/implement/constitution-enforcer/examples/good/compliance-report.md +57 -0
- package/skills/implement/constitution-enforcer/gotchas.md +26 -0
- package/skills/implement/constitution-enforcer/scripts/check-constitution.sh +88 -0
- package/skills/implement/no-go-zone-guard/SKILL.md +173 -0
- package/skills/implement/no-go-zone-guard/config.json +28 -0
- package/skills/implement/no-go-zone-guard/examples/good/adapter-workaround.md +46 -0
- package/skills/implement/no-go-zone-guard/gotchas.md +27 -0
- package/skills/implement/no-go-zone-guard/scripts/check-nogo-zones.sh +148 -0
- package/skills/implement/no-go-zone-guard/scripts/nogo-precommit.sh +96 -0
- package/skills/implement/tdd-driver/SKILL.md +159 -0
- package/skills/implement/tdd-driver/config.json +33 -0
- package/skills/implement/tdd-driver/examples/good/tdd-cycle-product-repo.md +81 -0
- package/skills/implement/tdd-driver/gotchas.md +34 -0
- package/skills/metrics/metrics-collector/SKILL.md +133 -0
- package/skills/metrics/metrics-collector/config.json +16 -0
- package/skills/metrics/metrics-collector/examples/bad/incomplete-report.md +48 -0
- package/skills/metrics/metrics-collector/examples/good/full-metrics-report.md +101 -0
- package/skills/metrics/metrics-collector/gotchas.md +26 -0
- package/skills/operations/incident-runbook/SKILL.md +167 -0
- package/skills/operations/incident-runbook/config.json +21 -0
- package/skills/operations/incident-runbook/examples/bad/vague-incident-report.md +48 -0
- package/skills/operations/incident-runbook/examples/good/p1-hotfix-response.md +119 -0
- package/skills/operations/incident-runbook/gotchas.md +26 -0
- package/skills/plan/architecture-designer/SKILL.md +228 -0
- package/skills/plan/architecture-designer/config.json +32 -0
- package/skills/plan/architecture-designer/examples/bad/vague-plan.md +62 -0
- package/skills/plan/architecture-designer/examples/good/expand-contract-migration.md +56 -0
- package/skills/plan/architecture-designer/examples/good/plan-structure.md +58 -0
- package/skills/plan/architecture-designer/gotchas.md +45 -0
- package/skills/plan/task-breakdown/SKILL.md +208 -0
- package/skills/plan/task-breakdown/config.json +26 -0
- package/skills/plan/task-breakdown/examples/bad/vague-tasks.md +77 -0
- package/skills/plan/task-breakdown/examples/good/spike-clarify-tasks.md +66 -0
- package/skills/plan/task-breakdown/examples/good/tasks-login-feature.md +111 -0
- package/skills/plan/task-breakdown/gotchas.md +39 -0
- package/skills/prototype/LOGIC.md +240 -0
- package/skills/prototype/SKILL.md +185 -0
- package/skills/prototype/UI.md +407 -0
- package/skills/prototype/config.json +104 -0
- package/skills/prototype/examples/bad/prototype-notes.md +68 -0
- package/skills/prototype/examples/good/prototype-notes-ui.md +109 -0
- package/skills/prototype/examples/good/prototype-notes.md +67 -0
- package/skills/prototype/gotchas.md +128 -0
- package/skills/prototype/scripts/check-flow-state.ps1 +112 -0
- package/skills/prototype/scripts/check-flow-state.sh +104 -0
- package/skills/prototype/scripts/check-prototype-cleanup.ps1 +124 -0
- package/skills/prototype/scripts/check-prototype-cleanup.sh +109 -0
- package/skills/prototype/scripts/check-prototype-notes.ps1 +107 -0
- package/skills/prototype/scripts/check-prototype-notes.sh +102 -0
- package/skills/review/adversarial-reviewer/SKILL.md +137 -0
- package/skills/review/adversarial-reviewer/config.json +32 -0
- package/skills/review/adversarial-reviewer/examples/good/review-report-template.md +56 -0
- package/skills/review/adversarial-reviewer/gotchas.md +46 -0
- package/skills/review/adversarial-reviewer/scripts/quick-security-scan.sh +52 -0
- package/skills/specify/ba-bpmn-doc-gen/SKILL.md +108 -0
- package/skills/specify/ba-bpmn-doc-gen/reference/reference-bpmn-generation.md +528 -0
- package/skills/specify/ba-bpmn-doc-gen/reference/reference-drawio-flowchart.md +466 -0
- package/skills/specify/ba-critic/SKILL.md +172 -0
- package/skills/specify/ba-critic/config.json +32 -0
- package/skills/specify/ba-critic/examples/good/critic-report-round1.md +51 -0
- package/skills/specify/ba-critic/gotchas.md +40 -0
- package/skills/specify/ba-critic/scripts/check-spec-quality.sh +72 -0
- package/skills/specify/ba-doc-generator/SKILL.md +102 -0
- package/skills/specify/ba-doc-generator/references/template-clevel.md +84 -0
- package/skills/specify/ba-doc-generator/references/template-compliance.md +83 -0
- package/skills/specify/ba-doc-generator/references/template-dev.md +138 -0
- package/skills/specify/ba-doc-generator/references/template-partner.md +167 -0
- package/skills/specify/ba-doc-generator/references/template-pm.md +92 -0
- package/skills/specify/ba-doc-generator/references/template-review.md +114 -0
- package/skills/specify/ba-doc-generator/references/template-tester.md +108 -0
- package/skills/specify/ba-doc-generator/references/template-user.md +98 -0
- package/skills/specify/bugfix-analyst/SKILL.md +296 -0
- package/skills/specify/bugfix-analyst/config.json +41 -0
- package/skills/specify/bugfix-analyst/examples/bad/common-mistakes.md +71 -0
- package/skills/specify/bugfix-analyst/examples/good/email-validation-bugfix.md +53 -0
- package/skills/specify/bugfix-analyst/gotchas.md +51 -0
- package/skills/specify/ears-writer/SKILL.md +129 -0
- package/skills/specify/ears-writer/config.json +20 -0
- package/skills/specify/ears-writer/examples/bad/common-mistakes.md +17 -0
- package/skills/specify/ears-writer/examples/good/login-requirements.md +41 -0
- package/skills/specify/ears-writer/gotchas.md +43 -0
- package/skills/specify/ears-writer/scripts/check-ears-compliance.sh +51 -0
- package/skills/test/test-case-generator/SKILL.md +161 -0
- package/skills/test/test-case-generator/config.json +33 -0
- package/skills/test/test-case-generator/examples/good/test-cases-login.md +104 -0
- package/skills/test/test-case-generator/gotchas.md +43 -0
- package/skills/understand/ba-docs-scanner/SKILL.md +239 -0
- package/skills/understand/ba-docs-scanner/config.json +47 -0
- package/skills/understand/ba-docs-scanner/examples/good/work-order-br-extract.md +28 -0
- package/skills/understand/ba-docs-scanner/gotchas.md +44 -0
- package/skills/understand/ba-docs-scanner/merge-rules.md +47 -0
- package/skills/understand/codebase-scanner/SKILL.md +260 -0
- package/skills/understand/codebase-scanner/config.json +56 -0
- package/skills/understand/codebase-scanner/examples/good/menu-module-output.md +44 -0
- package/skills/understand/codebase-scanner/gotchas.md +42 -0
- package/skills/understand/codebase-scanner/scripts/scan-project-structure.sh +64 -0
- package/templates/DESIGN.md +456 -0
- package/templates/agent-command-template.yaml +240 -0
- package/templates/agent-config-template.md +170 -0
- package/templates/agent-definition-template.md +145 -0
- package/templates/agent-metrics-template.md +150 -0
- package/templates/api-contract-template.md +72 -0
- package/templates/bugfix-report-template.md +195 -0
- package/templates/bugfix-spec-template.md +134 -0
- package/templates/code-review-report-template.md +119 -0
- package/templates/constitution-template.md +234 -0
- package/templates/context-template.md +94 -0
- package/templates/data-model-template.md +95 -0
- package/templates/decision-log-template.md +92 -0
- package/templates/flow-state-template.yaml +208 -0
- package/templates/github/workflows/v-flow-validate.yml +30 -0
- package/templates/knowledge/adr-template.md +70 -0
- package/templates/knowledge/api-contract-template.md +140 -0
- package/templates/knowledge/domain-glossary.md +29 -0
- package/templates/knowledge/golden-tests-readme.md +115 -0
- package/templates/knowledge/lessons-learned.md +41 -0
- package/templates/knowledge/patterns.md +103 -0
- package/templates/module-card/SKILL.md +85 -0
- package/templates/module-card/api-specs.md +96 -0
- package/templates/module-card/business-quiz.md +119 -0
- package/templates/module-card/cross-service.md +125 -0
- package/templates/module-card/db.md +85 -0
- package/templates/module-card/dev-quiz.md +62 -0
- package/templates/module-card/permissions.md +83 -0
- package/templates/module-card/state-diagram.md +64 -0
- package/templates/module-card/tech-context.md +90 -0
- package/templates/module-card/ui-flows.md +91 -0
- package/templates/module-card/use-cases.md +142 -0
- package/templates/module-template.yaml +161 -0
- package/templates/operations-report-template.md +108 -0
- package/templates/plan-template.md +308 -0
- package/templates/prototype-notes-template.md +116 -0
- package/templates/ptyc/PTYC.template.docx +0 -0
- package/templates/ptyc/ptyc.meta.example.yaml +44 -0
- package/templates/retrospective-report-template.md +136 -0
- package/templates/security-review-template.md +84 -0
- package/templates/session-template.md +167 -0
- package/templates/spec-review-log-template.md +75 -0
- package/templates/spec-template.md +229 -0
- package/templates/sprint-status-template.md +101 -0
- package/templates/tasks-template.md +275 -0
- package/templates/test-cases-template.md +124 -0
- package/templates/ux-checklist-template.md +79 -0
- package/templates/validation-report-template.md +125 -0
- package/templates/vflow-config-template.yaml +22 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_note": "setup_questions là PROMPT. Đáp án resolve persist vào .v-flow/config.yaml (xem .v-flow/templates/vflow-config-template.yaml). Skill đọc .v-flow/config.yaml trước, thiếu mới dùng default dưới đây.",
|
|
3
|
+
"answers_persisted_to": ".v-flow/config.yaml",
|
|
4
|
+
"setup_questions": [
|
|
5
|
+
{
|
|
6
|
+
"id": "test_framework",
|
|
7
|
+
"question": "Test framework nào đang dùng?",
|
|
8
|
+
"options": ["jest", "mocha", "vitest", "flutter_test", "pytest", "other"],
|
|
9
|
+
"default": "jest"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"id": "coverage_target",
|
|
13
|
+
"question": "Coverage target tối thiểu (%)?",
|
|
14
|
+
"type": "number",
|
|
15
|
+
"default": 80
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"id": "test_location",
|
|
19
|
+
"question": "Test files đặt ở đâu?",
|
|
20
|
+
"options": ["colocated", "test/", "__tests__/", "spec/"],
|
|
21
|
+
"default": "test/"
|
|
22
|
+
}
|
|
23
|
+
],
|
|
24
|
+
"hooks": {
|
|
25
|
+
"pre_implement": "Đọc test-cases.md → map TC-xxx cho TASK hiện tại",
|
|
26
|
+
"post_implement": "Chạy full test suite → verify không regression"
|
|
27
|
+
},
|
|
28
|
+
"memory": {
|
|
29
|
+
"file": "tdd-history.log",
|
|
30
|
+
"format": "[date] | [feature] | [task] | [tests_written] | [tests_passed] | [refactor_needed]",
|
|
31
|
+
"purpose": "Track TDD discipline — Agent đọc để biết patterns trước đó"
|
|
32
|
+
}
|
|
33
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Good Example — TDD Cycle cho T-003: Product Repository
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
- Task: Tạo ProductRepository với parameterized SQL
|
|
5
|
+
- REQ: REQ-U01 (parameterized queries), REQ-E05 (soft delete)
|
|
6
|
+
- Test cases: TC-01 (parameterized), TC-09 (soft delete)
|
|
7
|
+
|
|
8
|
+
## 🔴 RED — Viết test trước
|
|
9
|
+
|
|
10
|
+
```javascript
|
|
11
|
+
// test/repositories/product.repo.test.js
|
|
12
|
+
const { ProductRepository } = require('../../repositories/product.repo');
|
|
13
|
+
|
|
14
|
+
describe('ProductRepository', () => {
|
|
15
|
+
let repo, mockPool;
|
|
16
|
+
|
|
17
|
+
beforeEach(() => {
|
|
18
|
+
mockPool = { query: jest.fn() };
|
|
19
|
+
repo = new ProductRepository(mockPool);
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
// TC-01: REQ-U01 — parameterized query
|
|
23
|
+
it('should_use_parameterized_query_when_finding_by_id', async () => {
|
|
24
|
+
mockPool.query.mockResolvedValue({ rows: [{ id: 1, name: 'Test' }] });
|
|
25
|
+
|
|
26
|
+
await repo.findById(1);
|
|
27
|
+
|
|
28
|
+
// Assert: query uses $1 parameter, NOT string concat
|
|
29
|
+
const [sql, params] = mockPool.query.mock.calls[0];
|
|
30
|
+
expect(sql).toContain('$1');
|
|
31
|
+
expect(sql).not.toMatch(/['"]?\s*\+/); // no string concat
|
|
32
|
+
expect(params).toEqual([1]);
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
// TC-09: REQ-E05 — soft delete
|
|
36
|
+
it('should_set_deleted_at_when_soft_deleting', async () => {
|
|
37
|
+
mockPool.query.mockResolvedValue({ rowCount: 1 });
|
|
38
|
+
|
|
39
|
+
await repo.softDelete(1);
|
|
40
|
+
|
|
41
|
+
const [sql] = mockPool.query.mock.calls[0];
|
|
42
|
+
expect(sql).toContain('deleted_at');
|
|
43
|
+
expect(sql).not.toContain('DELETE FROM');
|
|
44
|
+
});
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Run → FAIL**: `ProductRepository is not defined` ✅ (expected)
|
|
49
|
+
|
|
50
|
+
## 🟢 GREEN — Code tối thiểu
|
|
51
|
+
|
|
52
|
+
```javascript
|
|
53
|
+
// repositories/product.repo.js
|
|
54
|
+
class ProductRepository {
|
|
55
|
+
constructor(pool) { this.pool = pool; }
|
|
56
|
+
|
|
57
|
+
async findById(id) {
|
|
58
|
+
const { rows } = await this.pool.query(
|
|
59
|
+
'SELECT * FROM products WHERE id = $1 AND deleted_at IS NULL', [id]
|
|
60
|
+
);
|
|
61
|
+
return rows[0] || null;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
async softDelete(id) {
|
|
65
|
+
const { rowCount } = await this.pool.query(
|
|
66
|
+
'UPDATE products SET deleted_at = NOW() WHERE id = $1', [id]
|
|
67
|
+
);
|
|
68
|
+
return rowCount > 0;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
module.exports = { ProductRepository };
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Run → PASS** ✅
|
|
75
|
+
|
|
76
|
+
## 🔵 REFACTOR — Clean theo constitution
|
|
77
|
+
|
|
78
|
+
- Extracted SQL strings to constants
|
|
79
|
+
- Added JSDoc comments
|
|
80
|
+
- Verified: all tests still pass ✅
|
|
81
|
+
- No-Go check: không đụng `db/pool.js` ✅
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Gotchas — TDD Driver
|
|
2
|
+
|
|
3
|
+
> Cập nhật liên tục khi Agent gặp edge case mới.
|
|
4
|
+
> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Anti-Patterns
|
|
9
|
+
|
|
10
|
+
1. ❌ **Implement trước, test sau** — Test sẽ bias theo code đã viết. "Green bar = proof" là ảo.
|
|
11
|
+
- **Hậu quả**: Test chỉ confirm code hoạt động, không confirm requirement.
|
|
12
|
+
|
|
13
|
+
2. ❌ **Skip test vì "đơn giản"** — Bugs hay ẩn ở code đơn giản nhất.
|
|
14
|
+
- **VD**: Off-by-one, null check, empty array.
|
|
15
|
+
|
|
16
|
+
3. ❌ **Test quá lớn** — 1 test cover 5 behaviors → khi fail, không biết cái nào sai.
|
|
17
|
+
- **Fix**: 1 test = 1 assertion = 1 behavior.
|
|
18
|
+
|
|
19
|
+
4. ❌ **Mock quá nhiều** — Test full mocks → integration issues leak ra production.
|
|
20
|
+
- **Rule**: Mock external deps only. Business logic test real code.
|
|
21
|
+
|
|
22
|
+
5. ❌ **Sửa test để pass** — Nếu test fail → fix CODE, KHÔNG fix test.
|
|
23
|
+
- **Exception**: Test implementation sai (sai mock setup, sai expected value) → fix test.
|
|
24
|
+
|
|
25
|
+
6. ❌ **Quên concerns** — W-xxx carry-forward từ R.0 phải được resolve trong TDD cycle.
|
|
26
|
+
- **Check**: Đọc `_session.md` → search `W-` → resolve trong task assigned.
|
|
27
|
+
|
|
28
|
+
7. ❌ **Test depend test khác** — Test 2 fail vì Test 1 setup shared state.
|
|
29
|
+
- **Fix**: Mỗi test PHẢI chạy standalone. Fresh state per test.
|
|
30
|
+
|
|
31
|
+
8. ❌ **Test tên vô nghĩa** — `test1`, `testLogin` → khi fail, không biết test gì.
|
|
32
|
+
- **Fix**: `should_return_404_when_product_not_found`.
|
|
33
|
+
|
|
34
|
+
9. ✅ **Nếu test PASS ngay ở RED** — Test SAI, không phải code ĐÚNG. Xem lại.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: metrics-collector
|
|
3
|
+
version: "1.0"
|
|
4
|
+
agent: metrics
|
|
5
|
+
phase: M.0
|
|
6
|
+
triggers:
|
|
7
|
+
- post_review
|
|
8
|
+
- manual_collection
|
|
9
|
+
dependencies:
|
|
10
|
+
- _shared/constitution-reader
|
|
11
|
+
input:
|
|
12
|
+
- .flow-state.yaml
|
|
13
|
+
- _session.md
|
|
14
|
+
- validation-report.md
|
|
15
|
+
- code-review-report.md (if exists)
|
|
16
|
+
- git log / timestamps
|
|
17
|
+
output:
|
|
18
|
+
- metrics-report.md
|
|
19
|
+
complexity: medium
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
# Metrics Collector Skill
|
|
23
|
+
|
|
24
|
+
> **Purpose**: Thu thập và phân tích Agent performance metrics sau mỗi feature cycle.
|
|
25
|
+
> **Khi nào dùng**: Sau khi R.1 (Review) hoàn tất — chạy `/v.metrics`.
|
|
26
|
+
|
|
27
|
+
## Quick Reference
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
Input: .flow-state.yaml + _session.md + validation/review reports
|
|
31
|
+
Output: metrics-report.md
|
|
32
|
+
Agent: Metrics Agent
|
|
33
|
+
Phase: M.0 (post R.1)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## What This Skill Does
|
|
37
|
+
|
|
38
|
+
1. **Collect Timeline Data** — Timestamps từ `.flow-state.yaml` phase_history
|
|
39
|
+
2. **Count Iterations** — Bao nhiêu lần revision tại mỗi phase
|
|
40
|
+
3. **Measure Quality** — First-pass approval rates, Master Check verdict
|
|
41
|
+
4. **Analyze Bottlenecks** — Phase nào mất thời gian nhất
|
|
42
|
+
5. **Generate Report** — Structured metrics-report.md
|
|
43
|
+
|
|
44
|
+
## Metrics Categories
|
|
45
|
+
|
|
46
|
+
### Per-Agent Metrics
|
|
47
|
+
|
|
48
|
+
| Metric | Source | Formula |
|
|
49
|
+
|--------|--------|---------|
|
|
50
|
+
| **First-pass approval rate** | `.flow-state.yaml` phase_history | phases_passed_first_try / total_phases |
|
|
51
|
+
| **Revision count** | `_session.md` execution trace | Count re-entries per phase |
|
|
52
|
+
| **Processing time** | `.flow-state.yaml` timestamps | exited_at - entered_at per phase |
|
|
53
|
+
| **Quality score** | `validation-report.md` | (PASS=100, WITH_CONCERNS=70, FAIL=0) |
|
|
54
|
+
|
|
55
|
+
### Per-Pipeline Metrics
|
|
56
|
+
|
|
57
|
+
| Metric | Source | Formula |
|
|
58
|
+
|--------|--------|---------|
|
|
59
|
+
| **Total cycle time** | `.flow-state.yaml` | last_phase.exited_at - first_phase.entered_at |
|
|
60
|
+
| **Master Check pass rate** | `.flow-state.yaml` routing | PASS_count / total_check_count |
|
|
61
|
+
| **Rework rate** | Phase history | phases_with_rework / total_phases |
|
|
62
|
+
| **Concern resolution rate** | `_session.md` | concerns_resolved / concerns_raised |
|
|
63
|
+
|
|
64
|
+
### Per-Feature Metrics
|
|
65
|
+
|
|
66
|
+
| Metric | Source | Formula |
|
|
67
|
+
|--------|--------|---------|
|
|
68
|
+
| **Requirements count** | `spec.md` | Count REQ-xxx |
|
|
69
|
+
| **Test coverage** | `test-cases.md` | tests_count / requirements_count |
|
|
70
|
+
| **Spec change count** | `.flow-state.yaml` spec_version | Version number (v1.0 → v1.2 = 2 changes) |
|
|
71
|
+
|
|
72
|
+
## How to Use
|
|
73
|
+
|
|
74
|
+
### Step 1: Gather Data Sources
|
|
75
|
+
|
|
76
|
+
```markdown
|
|
77
|
+
Đọc các file sau từ feature directory:
|
|
78
|
+
1. .flow-state.yaml → phase_history, artifacts, routing
|
|
79
|
+
2. _session.md → execution trace, decisions, open questions
|
|
80
|
+
3. validation-report.md → verdict, concerns
|
|
81
|
+
4. spec.md → requirements count
|
|
82
|
+
5. test-cases.md → test count
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Step 2: Calculate Metrics
|
|
86
|
+
|
|
87
|
+
```markdown
|
|
88
|
+
Cho mỗi phase trong phase_history:
|
|
89
|
+
- Tính duration = exited_at - entered_at
|
|
90
|
+
- Đếm số lần phase xuất hiện (revision count)
|
|
91
|
+
- Kiểm tra verdict/approval status
|
|
92
|
+
|
|
93
|
+
Tổng hợp:
|
|
94
|
+
- Total cycle time
|
|
95
|
+
- Bottleneck phase (longest duration)
|
|
96
|
+
- First-pass vs revision phases
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Step 3: Generate Report
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
## 📊 Metrics Report — [Feature Name]
|
|
103
|
+
|
|
104
|
+
### Summary
|
|
105
|
+
| Metric | Value |
|
|
106
|
+
|--------|-------|
|
|
107
|
+
| Total cycle time | X days |
|
|
108
|
+
| Phases completed | Y/Z |
|
|
109
|
+
| First-pass rate | XX% |
|
|
110
|
+
| Rework rate | XX% |
|
|
111
|
+
| Requirements | N |
|
|
112
|
+
| Test cases | M |
|
|
113
|
+
|
|
114
|
+
### Phase Timeline
|
|
115
|
+
| Phase | Duration | Revisions | Verdict |
|
|
116
|
+
|-------|----------|-----------|---------|
|
|
117
|
+
| S.1 | 2h | 0 | approved |
|
|
118
|
+
| B.0a | 1h | 0 | - |
|
|
119
|
+
| R.0 | 30m | 1 | PASS_WITH_CONCERNS |
|
|
120
|
+
| B.1 | 4h | 0 | - |
|
|
121
|
+
| R.1 | 1h | 0 | APPROVED |
|
|
122
|
+
|
|
123
|
+
### Recommendations
|
|
124
|
+
1. [Based on bottleneck analysis]
|
|
125
|
+
2. [Based on rework patterns]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Gotchas
|
|
129
|
+
|
|
130
|
+
1. **Missing timestamps** — Nếu `.flow-state.yaml` không có đủ timestamps, ước tính từ git log
|
|
131
|
+
2. **Manual phases** — Một số phases (e.g., human approval) không có agent metrics
|
|
132
|
+
3. **Cross-feature comparison** — Chỉ so sánh features cùng project_type (greenfield vs legacy)
|
|
133
|
+
4. **First feature bias** — Feature đầu tiên thường chậm hơn do setup overhead
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "metrics-collector",
|
|
3
|
+
"version": "1.0",
|
|
4
|
+
"description": "Collects and analyzes Agent performance metrics after each feature cycle",
|
|
5
|
+
"agent": "metrics",
|
|
6
|
+
"phase": ["M.0"],
|
|
7
|
+
"triggers": ["post_review", "manual"],
|
|
8
|
+
"dependencies": ["_shared/constitution-reader"],
|
|
9
|
+
"config": {
|
|
10
|
+
"metrics_categories": ["per_agent", "per_pipeline", "per_feature"],
|
|
11
|
+
"comparison_threshold": 5,
|
|
12
|
+
"report_format": "markdown",
|
|
13
|
+
"include_recommendations": true,
|
|
14
|
+
"benchmark_window": "last_5_features"
|
|
15
|
+
}
|
|
16
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Metrics Collector — Bad Example
|
|
2
|
+
|
|
3
|
+
> Ví dụ output THIẾU SÓT — không nên làm theo.
|
|
4
|
+
|
|
5
|
+
## ❌ Bad Output — Quá sơ sài
|
|
6
|
+
|
|
7
|
+
```markdown
|
|
8
|
+
## Metrics Report
|
|
9
|
+
|
|
10
|
+
Feature completed in 6 hours.
|
|
11
|
+
All tests passed.
|
|
12
|
+
No major issues.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Vấn đề
|
|
16
|
+
|
|
17
|
+
| # | Lỗi | Giải thích |
|
|
18
|
+
|---|------|-----------|
|
|
19
|
+
| 1 | Không có per-phase breakdown | Không biết phase nào bottleneck |
|
|
20
|
+
| 2 | Không có per-agent analysis | Không biết agent nào cần cải thiện |
|
|
21
|
+
| 3 | Không có benchmark comparison | "6 hours" có tốt hay không? |
|
|
22
|
+
| 4 | Không có trend data | Không biết đang cải thiện hay xuống |
|
|
23
|
+
| 5 | Không có recommendations | Metrics vô dụng nếu không actionable |
|
|
24
|
+
| 6 | Không track concerns | Concerns từ R.0 có resolved không? |
|
|
25
|
+
|
|
26
|
+
## ❌ Bad Output — Chỉ liệt kê không phân tích
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
## Metrics
|
|
30
|
+
|
|
31
|
+
- S.1: 1.5h
|
|
32
|
+
- B.0a: 45m
|
|
33
|
+
- B.0b: 30m
|
|
34
|
+
- R.0: 20m
|
|
35
|
+
- B.1: 2.5h
|
|
36
|
+
- R.1: 40m
|
|
37
|
+
|
|
38
|
+
Total: 6.5h
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Vấn đề
|
|
42
|
+
|
|
43
|
+
| # | Lỗi | Giải thích |
|
|
44
|
+
|---|------|-----------|
|
|
45
|
+
| 1 | Raw data không insight | Liệt kê số nhưng không phân tích |
|
|
46
|
+
| 2 | Thiếu context | Không biết revision count, verdict |
|
|
47
|
+
| 3 | Không có percentage | Không thấy proportions |
|
|
48
|
+
| 4 | Không actionable | Không biết cần làm gì tiếp |
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Metrics Collector — Good Example
|
|
2
|
+
|
|
3
|
+
> Ví dụ output chuẩn của Metrics Agent sau khi feature cycle hoàn tất.
|
|
4
|
+
|
|
5
|
+
## Input Context
|
|
6
|
+
|
|
7
|
+
**Feature:** 005-user-notifications
|
|
8
|
+
**Pipeline:** S.1 → B.0a ∥ B.0b → R.0 → B.1 → R.1 → M.0
|
|
9
|
+
**Outcome:** Deployed successfully
|
|
10
|
+
|
|
11
|
+
## Output — metrics-report.md
|
|
12
|
+
|
|
13
|
+
```markdown
|
|
14
|
+
## 📊 Metrics Report — 005-user-notifications
|
|
15
|
+
|
|
16
|
+
**Generated**: 2026-04-25 14:30
|
|
17
|
+
**Pipeline**: Full Flow (with Dual BA)
|
|
18
|
+
**Outcome**: ✅ Deployed
|
|
19
|
+
|
|
20
|
+
### Summary
|
|
21
|
+
|
|
22
|
+
| Metric | Value | Benchmark | Status |
|
|
23
|
+
|--------|-------|-----------|--------|
|
|
24
|
+
| Total cycle time | 6.5 hours | 4-8 hours | ✅ Normal |
|
|
25
|
+
| Phases completed | 7/7 | 7/7 | ✅ Complete |
|
|
26
|
+
| First-pass rate | 71% (5/7) | >60% | ✅ Good |
|
|
27
|
+
| Rework rate | 29% (2/7) | <40% | ✅ Acceptable |
|
|
28
|
+
| Requirements | 8 (3U + 2E + 2S + 1O) | — | — |
|
|
29
|
+
| Test cases | 15 | — | 1.88 per REQ |
|
|
30
|
+
| Spec changes | 2 (v1.0 → v1.2) | <3 | ✅ Normal |
|
|
31
|
+
|
|
32
|
+
### Phase Timeline
|
|
33
|
+
|
|
34
|
+
| Phase | Duration | Revisions | Verdict | Notes |
|
|
35
|
+
|-------|----------|-----------|---------|-------|
|
|
36
|
+
| S.1 Spec | 1.5h | 1 | approved v1.2 | Dual BA: 2 rounds to converge |
|
|
37
|
+
| B.0a Plan | 45m | 0 | approved | Clean architecture applied |
|
|
38
|
+
| B.0b Test | 30m | 0 | approved | 15 TCs (8 happy, 4 edge, 3 error) |
|
|
39
|
+
| R.0 Check | 20m | 1 | PASS_WITH_CONCERNS | [W-001] Missing pagination spec |
|
|
40
|
+
| B.1 Implement | 2.5h | 0 | — | TDD: all 15 tests pass |
|
|
41
|
+
| R.1 Review | 40m | 0 | APPROVED_WITH_NOTES | 4 issues (0 critical, 1 major, 3 minor) |
|
|
42
|
+
| M.0 Metrics | 15m | 0 | — | This report |
|
|
43
|
+
|
|
44
|
+
### Per-Agent Analysis
|
|
45
|
+
|
|
46
|
+
| Agent | First-pass? | Quality | Insight |
|
|
47
|
+
|-------|:-----------:|---------|---------|
|
|
48
|
+
| BA Agent | ❌ (rev 1) | Good | Spec v1.0 thiếu error paths → v1.2 after BA Critic |
|
|
49
|
+
| Plan Agent | ✅ | Excellent | Components mapped 100% to REQs |
|
|
50
|
+
| Test Agent | ✅ | Good | Coverage 1.88 TC/REQ — above target |
|
|
51
|
+
| Master Check | ❌ (rev 1) | Good | Caught [W-001] → resolved in B.1 |
|
|
52
|
+
| Implement Agent | ✅ | Excellent | TDD discipline maintained |
|
|
53
|
+
| Review Agent | ✅ | Good | Found 1 major (missing index) |
|
|
54
|
+
|
|
55
|
+
### Concern Resolution
|
|
56
|
+
|
|
57
|
+
| Concern | Source | Resolution | Verified |
|
|
58
|
+
|---------|--------|------------|:--------:|
|
|
59
|
+
| [W-001] Missing pagination | R.0 | Added pagination in B.1 (limit=20, offset) | ✅ R.1 |
|
|
60
|
+
|
|
61
|
+
### Bottleneck Analysis
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
Phase Duration Distribution:
|
|
65
|
+
S.1 ████████████████████ 1.5h (23%) ← Longest — Dual BA overhead
|
|
66
|
+
B.1 ██████████████████████████████████ 2.5h (38%) ← Expected — most work
|
|
67
|
+
B.0a ██████████ 45m (12%)
|
|
68
|
+
R.1 █████████ 40m (10%)
|
|
69
|
+
B.0b ██████ 30m (8%)
|
|
70
|
+
R.0 ████ 20m (5%)
|
|
71
|
+
M.0 ██ 15m (4%)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Bottleneck**: S.1 (23%) — Dual BA review added ~45m overhead.
|
|
75
|
+
**Action**: Consider using single BA for features with <5 requirements.
|
|
76
|
+
|
|
77
|
+
### Recommendations
|
|
78
|
+
|
|
79
|
+
1. **BA Agent**: Pre-define error paths in initial spec to reduce Dual BA rounds
|
|
80
|
+
2. **Master Check**: Pagination should be in standard checklist for list APIs
|
|
81
|
+
3. **Review Agent**: Database index check should be automated (add to constitution)
|
|
82
|
+
4. **Overall**: Cycle time within normal range — no urgent improvements needed
|
|
83
|
+
|
|
84
|
+
### Trend (last 3 features)
|
|
85
|
+
|
|
86
|
+
| Feature | Cycle Time | First-pass | Rework | REQs |
|
|
87
|
+
|---------|-----------|-----------|--------|------|
|
|
88
|
+
| 003-export | 4.0h | 83% | 17% | 5 |
|
|
89
|
+
| 004-dashboard | 7.5h | 57% | 43% | 12 |
|
|
90
|
+
| **005-notifications** | **6.5h** | **71%** | **29%** | **8** |
|
|
91
|
+
| **Average** | **6.0h** | **70%** | **30%** | **8.3** |
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Why This Is Good
|
|
95
|
+
|
|
96
|
+
1. ✅ **Quantitative** — tất cả metrics đều có số liệu cụ thể
|
|
97
|
+
2. ✅ **Benchmarked** — so sánh với benchmark biết normal hay không
|
|
98
|
+
3. ✅ **Actionable** — recommendations cụ thể cho từng agent
|
|
99
|
+
4. ✅ **Visual** — bar chart cho bottleneck analysis
|
|
100
|
+
5. ✅ **Trending** — so sánh với features trước để thấy xu hướng
|
|
101
|
+
6. ✅ **Concern tracking** — chứng minh concerns đã resolved
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Metrics Collector — Gotchas & Common Mistakes
|
|
2
|
+
|
|
3
|
+
## ⚠️ Gotcha 1: Vanity Metrics
|
|
4
|
+
|
|
5
|
+
**Sai**: Focus vào "total features completed" — không phản ánh quality.
|
|
6
|
+
**Đúng**: Đo **first-pass approval rate** và **rework rate** — phản ánh thực sự Agent performance.
|
|
7
|
+
|
|
8
|
+
## ⚠️ Gotcha 2: Missing Baseline
|
|
9
|
+
|
|
10
|
+
**Sai**: Report metrics mà không có benchmark.
|
|
11
|
+
**Đúng**: So sánh với 5 features gần nhất. Feature đầu tiên là baseline, không phải target.
|
|
12
|
+
|
|
13
|
+
## ⚠️ Gotcha 3: Ignoring Context
|
|
14
|
+
|
|
15
|
+
**Sai**: So sánh cycle time giữa simple CRUD feature và complex integration feature.
|
|
16
|
+
**Đúng**: Normalize theo requirements count. Report requirements/hour thay vì absolute time.
|
|
17
|
+
|
|
18
|
+
## ⚠️ Gotcha 4: Skipping Recommendations
|
|
19
|
+
|
|
20
|
+
**Sai**: Chỉ report numbers, không đề xuất action.
|
|
21
|
+
**Đúng**: Mỗi metrics report PHẢI có ≥2 actionable recommendations dựa trên bottleneck analysis.
|
|
22
|
+
|
|
23
|
+
## ⚠️ Gotcha 5: Over-optimization
|
|
24
|
+
|
|
25
|
+
**Sai**: Mỗi feature đều thay đổi agent-config.md dựa trên metrics.
|
|
26
|
+
**Đúng**: Chỉ update agent config sau 5-10 features. Trends matter, not individual data points.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: incident-runbook
|
|
3
|
+
version: "1.0"
|
|
4
|
+
agent: operations
|
|
5
|
+
phase: O.0
|
|
6
|
+
triggers:
|
|
7
|
+
- production_incident
|
|
8
|
+
- hotfix_flow
|
|
9
|
+
- monitoring_alert
|
|
10
|
+
dependencies:
|
|
11
|
+
- _shared/context-reader
|
|
12
|
+
input:
|
|
13
|
+
- incident report / alert
|
|
14
|
+
- monitoring data (logs, metrics)
|
|
15
|
+
- context.md
|
|
16
|
+
- spec.md (related feature)
|
|
17
|
+
output:
|
|
18
|
+
- operations-report.md
|
|
19
|
+
- incident ticket (INC-XXX.md)
|
|
20
|
+
complexity: high
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
# Incident Runbook Skill
|
|
24
|
+
|
|
25
|
+
> **Purpose**: Structured incident response procedure cho production issues.
|
|
26
|
+
> **Khi nào dùng**: Khi nhận alert/report từ production — chạy `/v.hotfix`.
|
|
27
|
+
|
|
28
|
+
## Quick Reference
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Input: Incident report + monitoring data + context.md
|
|
32
|
+
Output: operations-report.md + INC-XXX.md
|
|
33
|
+
Agent: Operations Agent
|
|
34
|
+
Phase: O.0
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## What This Skill Does
|
|
38
|
+
|
|
39
|
+
1. **Triage** — Phân loại severity (P1/P2/P3/P4) và assign response SLA
|
|
40
|
+
2. **Investigate** — Root Cause Analysis (RCA) có cấu trúc
|
|
41
|
+
3. **Contain** — Immediate mitigation steps
|
|
42
|
+
4. **Fix** — Route to appropriate pipeline (hotfix/quickfix/standard)
|
|
43
|
+
5. **Learn** — Post-mortem và lessons learned
|
|
44
|
+
|
|
45
|
+
## Severity Classification
|
|
46
|
+
|
|
47
|
+
| Level | Impact | Response SLA | Pipeline |
|
|
48
|
+
|-------|--------|-------------|----------|
|
|
49
|
+
| **P1** | Service down, data loss | < 15 min | `/v.hotfix` |
|
|
50
|
+
| **P2** | Major feature broken | < 1 hour | `/v.hotfix` |
|
|
51
|
+
| **P3** | Minor feature degraded | < 4 hours | `/v.quickfix` |
|
|
52
|
+
| **P4** | Cosmetic, performance | Next sprint | Standard flow |
|
|
53
|
+
|
|
54
|
+
## Incident Response Steps
|
|
55
|
+
|
|
56
|
+
### Step 1: Triage (< 5 min)
|
|
57
|
+
|
|
58
|
+
```markdown
|
|
59
|
+
## Incident Triage
|
|
60
|
+
|
|
61
|
+
**Alert Source**: [monitoring / user report / automated test]
|
|
62
|
+
**Timestamp**: [when detected]
|
|
63
|
+
**Impact Assessment**:
|
|
64
|
+
- Users affected: [all / segment / single]
|
|
65
|
+
- Feature affected: [feature name]
|
|
66
|
+
- Data integrity: [safe / at risk / compromised]
|
|
67
|
+
|
|
68
|
+
**Severity**: P[1-4]
|
|
69
|
+
**Response SLA**: [time]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Step 2: Investigate (RCA)
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
## Root Cause Analysis
|
|
76
|
+
|
|
77
|
+
### What happened?
|
|
78
|
+
[Description của incident]
|
|
79
|
+
|
|
80
|
+
### Timeline
|
|
81
|
+
| Time | Event |
|
|
82
|
+
|------|-------|
|
|
83
|
+
| T-0 | Description of the trigger event |
|
|
84
|
+
| T+5m | First alert |
|
|
85
|
+
| T+10m | Investigation started |
|
|
86
|
+
|
|
87
|
+
### Root Cause
|
|
88
|
+
[Direct cause → Contributing factors → Systemic issues]
|
|
89
|
+
|
|
90
|
+
### Blast Radius
|
|
91
|
+
- Files affected: [list]
|
|
92
|
+
- Modules affected: [list]
|
|
93
|
+
- No-Go Zones touched: [yes/no — CRITICAL if yes]
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Step 3: Contain
|
|
97
|
+
|
|
98
|
+
```markdown
|
|
99
|
+
## Immediate Mitigation
|
|
100
|
+
|
|
101
|
+
### Actions Taken
|
|
102
|
+
1. [Rollback / Feature flag / Rate limit / etc.]
|
|
103
|
+
2. [Communication to users]
|
|
104
|
+
3. [Monitoring enhanced]
|
|
105
|
+
|
|
106
|
+
### Verification
|
|
107
|
+
- [How to verify the containment is effective]
|
|
108
|
+
- [Metrics to watch]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Step 4: Fix (Route to Pipeline)
|
|
112
|
+
|
|
113
|
+
```markdown
|
|
114
|
+
## Fix Strategy
|
|
115
|
+
|
|
116
|
+
### Route Decision
|
|
117
|
+
- P1/P2 → `/v.hotfix` — skip spec, direct implement → review → deploy
|
|
118
|
+
- P3 → `/v.quickfix` — minimal spec → implement → review
|
|
119
|
+
- P4 → Standard flow with backlog ticket
|
|
120
|
+
|
|
121
|
+
### Fix Details
|
|
122
|
+
- Branch: hotfix/INC-XXX
|
|
123
|
+
- Files to change: [list]
|
|
124
|
+
- Test strategy: [unit test for fix + regression]
|
|
125
|
+
- Deploy strategy: [immediate / canary / next release]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Step 5: Learn (Post-mortem)
|
|
129
|
+
|
|
130
|
+
```markdown
|
|
131
|
+
## Post-Mortem
|
|
132
|
+
|
|
133
|
+
### What went well
|
|
134
|
+
1. [Detection was fast]
|
|
135
|
+
2. [Communication was clear]
|
|
136
|
+
|
|
137
|
+
### What went wrong
|
|
138
|
+
1. [Missing test coverage for edge case]
|
|
139
|
+
2. [No monitoring for this metric]
|
|
140
|
+
|
|
141
|
+
### Action Items
|
|
142
|
+
| # | Action | Owner | Due |
|
|
143
|
+
|---|--------|-------|-----|
|
|
144
|
+
| 1 | Add test for edge case X | Dev | Sprint N |
|
|
145
|
+
| 2 | Add monitoring alert for Y | SRE | Sprint N |
|
|
146
|
+
| 3 | Update context.md with new no-go zone | Tech Lead | Sprint N |
|
|
147
|
+
|
|
148
|
+
### Knowledge Base Update
|
|
149
|
+
→ File: .v-flow/knowledge/lessons-learned/INC-XXX.md
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Integration with V-Flow Pipeline
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
Alert → O.0 (Triage + RCA) → Route Decision:
|
|
156
|
+
├── P1/P2 → B.1 (Hotfix) → R.1 (Review) → Deploy → O.0 (Verify)
|
|
157
|
+
├── P3 → S.1 (Quick Spec) → B.1 → R.1 → Deploy
|
|
158
|
+
└── P4 → Backlog → Standard Pipeline
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Gotchas
|
|
162
|
+
|
|
163
|
+
1. **Đừng debug production trên production** — Reproduce locally trước khi fix
|
|
164
|
+
2. **No-Go Zones** — Nếu root cause nằm trong no-go zone, PHẢI escalate tới Tech Lead
|
|
165
|
+
3. **Hotfix ≠ Skip quality** — Hotfix vẫn cần test và review, chỉ skip spec
|
|
166
|
+
4. **Communication** — Cập nhật stakeholders tại mỗi bước, không chỉ khi fix xong
|
|
167
|
+
5. **Lessons learned** — Post-mortem PHẢI được ghi vào knowledge base, không chỉ chat/email
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "incident-runbook",
|
|
3
|
+
"version": "1.0",
|
|
4
|
+
"description": "Structured incident response procedure for production issues",
|
|
5
|
+
"agent": "operations",
|
|
6
|
+
"phase": ["O.0"],
|
|
7
|
+
"triggers": ["production_incident", "monitoring_alert", "hotfix_flow"],
|
|
8
|
+
"dependencies": ["_shared/context-reader"],
|
|
9
|
+
"config": {
|
|
10
|
+
"severity_levels": {
|
|
11
|
+
"P1": { "sla_minutes": 15, "route": "hotfix" },
|
|
12
|
+
"P2": { "sla_minutes": 60, "route": "hotfix" },
|
|
13
|
+
"P3": { "sla_minutes": 240, "route": "quickfix" },
|
|
14
|
+
"P4": { "sla_minutes": null, "route": "standard" }
|
|
15
|
+
},
|
|
16
|
+
"require_postmortem": true,
|
|
17
|
+
"incident_dir": ".v-flow/incidents",
|
|
18
|
+
"lessons_learned_dir": ".v-flow/knowledge/lessons-learned",
|
|
19
|
+
"report_format": "markdown"
|
|
20
|
+
}
|
|
21
|
+
}
|