diff --git a/README.md b/README.md index 251881d3..9b882b9e 100644 --- a/README.md +++ b/README.md @@ -233,7 +233,7 @@ Disable any pillar individually via env var: `AF_SELF_HEAL_DISABLED`, `AF_MCP_AU ## Works Across AI Coding Tools -Aura Frog's 72 rules, 42 skills, and 15 agents are **~87% portable** (weighted average) because they're markdown conventions, not tool-specific code. Only the thin hook layer needs adapters. +Aura Frog's 72 rules, 43 skills, and 15 agents are **~87% portable** (weighted average) because they're markdown conventions, not tool-specific code. Only the thin hook layer needs adapters. | Tool | Status | Coverage | |------|--------|:--------:| @@ -311,7 +311,7 @@ Expected output: 🐸 Aura Frog v3.8.0-alpha.12 — Ready Agents: 15 loaded (lead, architect, frontend, mobile, tester, security, devops, strategist, scanner, master-planner, feature-architect, story-planner, replanner, epic-summarizer, conflict-arbiter) - Skills: 42 available (9 auto-invoke, 33 on-demand) + Skills: 43 available (10 auto-invoke, 33 on-demand) Rules: 72 loaded (22 core + 20 agent + 30 workflow) Hooks: 51 registered MCP: context7, playwright, vitest, firebase, figma, slack @@ -441,7 +441,7 @@ Details: `rules/core/execution-rules.md`, `skills/agent-detector/SKILL.md`, `ski | Component | Count | Why it matters | |-----------|:-----:|----------------| | **Agents** | 15 | Right expert auto-selected per task (build + review + planning + safety roles) | -| **Skills** | 42 | 9 auto-invoke on context, 33 on-demand (incl. `design-vision-loop`) | +| **Skills** | 43 | 10 auto-invoke on context, 33 on-demand (incl. `design-vision-loop`) | | **Commands** | 24 | Core: `/run`, `/check`, `/design`, `/project`, `/af`, `/help` + `/aura-frog:*` hierarchical-planning suite (14 user-facing + 10 legacy `/aura-frog:plan-` alias stubs) | | **Rules** | 72 | 3-tier loading (22 core + 20 agent + 30 workflow) — only what's needed | | **Hooks** | 51 | Conditional — skip processing for non-code files (v3.7.2 adds `bare-word-router.cjs`) | @@ -629,7 +629,7 @@ Honest comparison with two popular plugins in the ecosystem (April 2026). | | **Aura Frog** | **wshobson/agents** | **Superpowers** | |---|---|---|---| | **Agents** | 15 curated | 184 across 78 plugins | ~20 | -| **Skills** | 42 | 150 | Small focused set | +| **Skills** | 43 | 150 | Small focused set | | **Commands** | 24 (14 user-facing + 10 legacy aliases) | 98 | ~10 | | **Workflow** | 5-phase TDD with 2 gates | No structured workflow | Phase-gated workflow | | **Agent routing** | Task-content Layer 0 override | Manual `/agent-name` | Similar to Aura Frog | @@ -685,7 +685,7 @@ Use this checklist: - ✅ MCP-heavy workflows (Figma + Firebase + Slack + DBs) → per-agent allowlists + audit log - ⚠️ Single-file edits / quick prototypes → workflow overhead may not pay off; use `/run task: …` to bypass - ⚠️ Haiku-only budget — some features (planning, conflict, design phases) prefer Sonnet/Opus -- ⚠️ Minimalist-plugin preference — Aura Frog is substantial (15 agents, 42 skills, 72 rules, 51 hooks) +- ⚠️ Minimalist-plugin preference — Aura Frog is substantial (15 agents, 43 skills, 72 rules, 51 hooks) --- @@ -697,7 +697,7 @@ Use this checklist: | **Getting Started** | [GET_STARTED.md](docs/getting-started/GET_STARTED.md) | | **First Workflow Tutorial** | [FIRST_WORKFLOW_TUTORIAL.md](docs/getting-started/FIRST_WORKFLOW_TUTORIAL.md) | | **All Commands (24)** | [commands/README.md](aura-frog/commands/README.md) | -| **All Skills (42)** | [skills/README.md](aura-frog/skills/README.md) | +| **All Skills (43)** | [skills/README.md](aura-frog/skills/README.md) | | **Agent Teams Guide** | [AGENT_TEAMS_GUIDE.md](docs/guides/AGENT_TEAMS_GUIDE.md) | | **MCP Setup** | [MCP_GUIDE.md](docs/operations/MCP_GUIDE.md) | | **Hooks & Lifecycle** | [hooks/README.md](aura-frog/hooks/README.md) | @@ -715,7 +715,7 @@ TOON = Compression Approval Gates = Interrupts Handoffs = IPC aura-frog/ ├── agents/ 15 processes (auto-dispatched per task) -├── skills/ 42 skills (9 auto-invoke + 33 on-demand) +├── skills/ 43 skills (10 auto-invoke + 33 on-demand) ├── commands/ 24 commands (core /run /check /design /project /af /help + /aura-frog:* hierarchical-planning suite) ├── rules/ 72 rules (22 core + 20 agent + 30 workflow) ├── hooks/ 50 lifecycle hooks (conditional execution) diff --git a/aura-frog/.claude-plugin/plugin.json b/aura-frog/.claude-plugin/plugin.json index b9729e81..7c723e3f 100644 --- a/aura-frog/.claude-plugin/plugin.json +++ b/aura-frog/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "aura-frog", "version": "3.8.0-alpha.12", - "description": "Planning-first LLM OS for software engineering. Hierarchical planning (T0-T4) survives session reset · forensic reasoning traces · L1+L2 conflict detection · self-healing safety gates · per-agent MCP security · durable project-context snapshots · cross-tool porter (Copilot/Codex/Cursor) · CLI dashboard. 15 agents, 5-phase TDD, 72 rules (3-tier), 42 skills, 24 commands, 51 hooks, 6 MCP servers. ~87% markdown. Backward-compatible with /run.", + "description": "Planning-first LLM OS for software engineering. Hierarchical planning (T0-T4) survives session reset · forensic reasoning traces · L1+L2 conflict detection · self-healing safety gates · per-agent MCP security · durable project-context snapshots · cross-tool porter (Copilot/Codex/Cursor) · CLI dashboard. 15 agents, 5-phase TDD, 72 rules (3-tier), 43 skills, 24 commands, 51 hooks, 6 MCP servers. ~87% markdown. Backward-compatible with /run.", "author": { "name": "Nguyen Thien Thanh", "email": "nguyenthienthanh.kiyoshi@gmail.com", diff --git a/aura-frog/CLAUDE.md b/aura-frog/CLAUDE.md index 6bde33ed..0dced730 100644 --- a/aura-frog/CLAUDE.md +++ b/aura-frog/CLAUDE.md @@ -279,7 +279,7 @@ resources[8]{name,location}: Agents (15),agents/ Commands (24),commands/ Rules (72),rules/{core|agent|workflow}/ - Skills (42),skills/ + Skills (43),skills/ Hooks (51),hooks/ MCP (6),.mcp.json (all enabled; postgres/redis/chrome-devtools/codebase-memory/stitch unbundled — see docs/operations/MCP_GUIDE.md) AI References,docs/ diff --git a/aura-frog/README.md b/aura-frog/README.md index 50acd782..40b94a76 100644 --- a/aura-frog/README.md +++ b/aura-frog/README.md @@ -592,7 +592,7 @@ This overrides every agent/skill `model:` declaration. See [Per-Agent Model Over /run worktree: # Automatically creates isolated worktree + runs there ``` -Each worktree has its own state in `.claude/logs/runs//`. See [Git Worktree skill](aura-frog/skills/git-worktree/SKILL.md). +Each worktree has its own state in `.claude/logs/runs//`. See the [git skill](aura-frog/skills/git/SKILL.md). For full multi-agent parallel work, enable Agent Teams: ```bash diff --git a/aura-frog/rules/workflow/workflow-deliverables.md b/aura-frog/rules/workflow/workflow-deliverables.md index d2c70a9e..f58da0c6 100644 --- a/aura-frog/rules/workflow/workflow-deliverables.md +++ b/aura-frog/rules/workflow/workflow-deliverables.md @@ -26,10 +26,12 @@ Syntax: `files[3]{path,action,purpose}:` for tabular data. See [TOON format](htt ## Phase Deliverables ```toon -deliverables[12]{phase,document,required,key_content}: +deliverables[14]{phase,document,required,key_content}: 1,REQUIREMENTS.md,YES,User stories + acceptance criteria + scope 1,TECH_SPEC.md,YES,AI-readable: architecture + files + APIs + risks 1,TECH_SPEC_CONFLUENCE.md,YES,Human-readable: full Confluence format + 1,DESIGN_DECISIONS.md,YES,Decision records — tiered Y-statement/ADR/MADR/RFC + 1,LLD.md,If design-heavy,Low-level design — data/API/errors/ops 1,UI_BREAKDOWN.md,If UI,Components + props + accessibility 2,TEST_PLAN.md,YES,Test scenarios + coverage targets 2,Test files,YES,Failing tests (TDD RED) @@ -52,6 +54,8 @@ deliverables[12]{phase,document,required,key_content}: ├── REQUIREMENTS.md ├── TECH_SPEC.md # AI reads this ├── TECH_SPEC_CONFLUENCE.md # Human-readable +├── DESIGN_DECISIONS.md # Decision records (tiered) +├── LLD.md # Low-level design (if design-heavy) ├── UI_BREAKDOWN.md # If UI ├── TEST_PLAN.md ├── CODE_REVIEW.md diff --git a/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh b/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh index 8535978b..2c4643bb 100755 --- a/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh +++ b/aura-frog/scripts/workflow/scaffold-phase-deliverables.sh @@ -106,7 +106,8 @@ scaffold_phase() { scaffold_one 1 "REQUIREMENTS.md" "requirements.md" scaffold_one 1 "TECH_SPEC.md" "tech-spec-toon.md" scaffold_one 1 "TECH_SPEC_CONFLUENCE.md" "confluence-page.md" - scaffold_one 1 "DESIGN_DECISIONS.md" "lld.md" + scaffold_one 1 "DESIGN_DECISIONS.md" "decision-record.md" + scaffold_one 1 "LLD.md" "lld.md" ;; 2) scaffold_one 2 "TEST_PLAN.md" "test-plan-toon.md" diff --git a/aura-frog/skills/documentation/SKILL.md b/aura-frog/skills/documentation/SKILL.md index 86fdb4c5..45108384 100644 --- a/aura-frog/skills/documentation/SKILL.md +++ b/aura-frog/skills/documentation/SKILL.md @@ -1,6 +1,6 @@ --- name: documentation -description: "Create Architecture Decision Records (ADRs) and Runbooks for operational documentation." +description: "Create Runbooks for operational documentation. For ADRs, tech specs, requirements, LLD and technical analysis use the tech-writing skill instead." autoInvoke: false priority: medium triggers: @@ -19,8 +19,10 @@ user-invocable: false ## When to Create -- **ADR:** Technology choices, architectural changes, new patterns, deprecations - **Runbook:** Service deployment, common ops tasks, incident response +- **ADR:** → use `skills/tech-writing` + `templates/decision-record.md`. That template carries the + full 4-tier ladder (Y-statement → Nygard ADR → MADR → RFC) and picks the tier by decision size. + The stripped ADR template below is kept only so existing links keep resolving. ## ADR Template diff --git a/aura-frog/skills/tech-writing/SKILL.md b/aura-frog/skills/tech-writing/SKILL.md new file mode 100644 index 00000000..f8583b4d --- /dev/null +++ b/aura-frog/skills/tech-writing/SKILL.md @@ -0,0 +1,321 @@ +--- +name: tech-writing +description: "Write professional technical documents — requirements/PRD, tech spec/design doc, low-level design, decision records, and trade-off analysis — at a formality tier matched to the task. Grounds every claim in real code or a cited source, marks what it could not verify, and refuses to pad. Use when asked to write/update a spec, requirements, design doc, LLD, ADR, RFC, or technical analysis." +autoInvoke: true +priority: high +triggers: + - "write a spec" + - "tech spec" + - "design doc" + - "requirements" + - "PRD" + - "low-level design" + - "LLD" + - "ADR" + - "RFC" + - "technical analysis" + - "trade-off" +allowed-tools: Read, Grep, Glob, Bash, Write, Edit, WebFetch +effort: high +user-invocable: false +--- + +> **AI-consumed reference.** Optimized for Claude to read during execution. + +# Technical Writing + +Produce documents a reviewer can **act on and argue with** — not filled-in templates. + +> **Evidence policy for this skill itself.** Almost everything below is **CONVENTION** with an +> authoritative primary source, NOT measured efficacy. No study shows these structures produce better +> outcomes. The three places carrying real measurement are marked **[MEASURED]**. Never present +> convention as research-backed — that is the first thing this skill exists to stop. + +--- + +## Step 0 — Refuse to write blind + +Run `rules/core/prompt-validation.md` (6-dimension gate) BEFORE writing. Below threshold → ask the +1–2 weakest dimensions, do not guess. A doc written from guesses is worse than no doc: it looks +authoritative and is wrong. + +Then answer three questions **in the output header**, so the reader sees the frame: + +```toon +frame[3]{question,why}: + Who reads this and what decision do they make with it?,"No audience ⇒ no way to judge detail level" + What is ALREADY true (code/system) vs PROPOSED?,"The #1 source of misleading specs" + What would make this document WRONG?,"If nothing could, it is asserting nothing" +``` + +--- + +## Step 1 — Pick the tier. Default DOWN. + +Tier follows `agent-detector` complexity. **Do not scale formality with the effort you spent.** + +```toon +tiers[4]{tier,complexity,doc,gate}: + T0,Quick,"Y-statement (1 sentence) or a PR-description paragraph","Reversible? cheap to undo? stop here" + T1,Standard,"Nygard ADR (5 sections) OR a one-page spec","Long-lived consequence but one obvious option" + T2,Deep,"MADR + LLD sections that apply","≥2 options genuinely worth comparing" + T3,Project,"RFC: guide-level + reference-level split","Crosses teams / hard to reverse" +``` + +**Escalate a tier when** ≥2 hold: multiple teams affected · hard to reverse · ≥2 credible options · +safety/money/data-loss exposure · the reader will not be in the room to ask you. +**Never escalate** because the topic feels important. + +Templates: `templates/decision-record.md` (all 4 tiers in one file — delete unused tiers), +`templates/requirements.md`, `templates/tech-spec-toon.md`, `templates/lld.md`. + +### State, not polish + +Stamp every document with a state from Oxide's RFD lifecycle — there is deliberately **no `draft`**: + +`ideation → discussion → published → committed → abandoned` + +`committed` = "this describes the system as it RUNS, not a future intention". Shipping an honestly +labelled `ideation` doc beats withholding until polished (norm inherited from IETF RFC 3, 1969: +*"Notes are encouraged to be timely rather than polished."*). + +--- + +## Step 2 — Ground before drafting (NOT after) + +**Order is load-bearing.** Extract evidence first, then write. Never draft then hunt for support. + +1. **Quote first.** For any source >20k tokens, extract **word-for-word quotes** BEFORE analysing. + Anthropic guidance, verbatim: *"ask Claude to extract word-for-word quotes first before performing + its task. This grounds its responses in the actual text."* +2. **Every claim about this codebase needs a prior `Read`.** Per `rules/core/grounding-discipline.md`, + a claim is grounded only if a preceding `file_read` covers the file/function/symbol it names. + This is a deterministic check — no LLM judgement, no cost. It is the strongest tool available here. +3. **Cite inline** as `path/to/file.ts:120-134`, never "the auth module handles this". +4. **Retract what you cannot support.** After drafting, for each claim find a supporting quote; if + none exists, **delete the claim and mark the hole** — do not soften it into vagueness. +5. **"I don't know" is a valid output.** Say *"Not verified: "*. + Vendor guidance is explicit that permitting uncertainty *"can drastically reduce false information."* + +Mark every non-obvious claim with its evidence level: + +```toon +evidence[4]{tag,meaning}: + [CODE],"Read in this session — cite file:line" + [SOURCE],"External source — cite URL + verbatim quote" + [CONVENTION],"Standard/common practice — name the standard; NOT proof it works" + [UNVERIFIED],"Believed but not checked — say what would check it" +``` + +--- + +## Step 3 — Verify with an INDEPENDENT pass, never self-critique in place + +**[MEASURED] — this is the one place with hard numbers, and they say the intuitive approach backfires.** + +Intrinsic self-correction (re-read your own draft and fix it, no external input) **degrades** output. +Huang et al., *LLMs Cannot Self-Correct Reasoning Yet*, **ICLR 2024** (arXiv 2310.01798, Table 3): + +| Model · benchmark | initial | round 1 | round 2 | +|---|---|---|---| +| GPT-4 · GSM8K | 95.5 | 91.5 | 89.0 | +| GPT-3.5 · CommonSenseQA | 75.8 | 38.1 | 41.8 | + +The reported gains in earlier self-correction work came from **oracle labels**; *"the improvements +vanish when oracle labels are not available."* Multi-agent debate does **not** rescue it — at matched +budget it loses to plain self-consistency (GSM8K: debate 83.2 @6 responses vs self-consistency 85.3 +@6; 83.0 @9 vs 88.2 @9, Table 7). + +**Therefore: never grade your own draft in the draft's context.** Do this instead: + +1. Draft. +2. Plan verification questions against the draft. +3. **Answer each question independently — fresh context, without the draft visible.** This is the + load-bearing detail of Chain-of-Verification (Dhuliawala et al., arXiv 2309.11495): *"answers + those questions independently so the answers are not biased by other responses."* Verify inside + the draft's context and the effect is lost. +4. Revise against the answers. + +Use the `chain-of-verification` skill for this loop. **Prefer an EXTERNAL verifier wherever one +exists** — run the test, execute the snippet, `curl` the endpoint, read the migration. A tool result +beats any amount of model deliberation. + +> **Limit, stated by the vendor:** *"while these techniques significantly reduce hallucinations, they +> don't eliminate them entirely. Always validate critical information."* Do not promise a clean doc. + +--- + +## Step 4 — Requirements: use the C/R/A triad + +**ISO/IEC/IEEE 29148:2018** is the normative standard (active; superseded IEEE 830-1998 via the 2011 +edition, which also replaced IEEE 1233 and IEEE 1362). It separates characteristics of an individual +requirement (§5.2.5) from characteristics of a **set** (§5.2.6), plus language criteria (§5.2.7) and +attributes (§5.2.8). The clause text is paywalled — do not quote names as if read from it. + +**INCOSE GtWR v4** (INCOSE-TP-2010-006-04, 2023) is society **guidance**, not a standard, and is +free. Use it as the working rubric: + +```toon +individual[9]{id,characteristic}: + C1,Necessary + C2,Appropriate + C3,Unambiguous + C4,Complete + C5,Singular + C6,Feasible + C7,Verifiable + C8,Correct + C9,Conforming +``` + +```toon +set[6]{id,characteristic}: + C10,Complete + C11,Consistent + C12,Feasible + C13,Comprehensible + C14,Able to be validated + C15,Correct +``` + +*(Complete/Feasible/Correct deliberately appear in both lists — they mean different things about one +requirement vs about the set.)* + +**Lintable subset of R1–R42.** GtWR has 42 rules in 14 quality-focus groups, but INCOSE §1.8 states +NLP/AI tools *"do not address all the rules"* and validation *"cannot be done without the project +team doing the analysis manually."* **Never advertise "42 automated checks."** Mechanically checkable: + +```toon +lint[6]{rule,check}: + R7,"Ban vague terms: some / any / several / many / about / approximate" + R8,"Ban escape clauses: as appropriate / as required / to the extent practical / if practicable" + R18-R23,"Singularity — one 'shall' per statement; flag 'and'/'or' joining obligations" + R32,"Quantifiers — flag all/every/none without a defined scope" + R33-R35,"Tolerance/quantification — flag a number with no unit or no tolerance" + R36-R40,"Uniformity — same term for same concept throughout" +``` + +Everything else needs human/LLM judgement. Say so. + +**Attributes per requirement** — GtWR A1–A49 recommended minimum (marked `*` in the source). This is +the traceability schema; put it in front-matter: + +`Rationale · Trace to Parent · Trace to Source · Verification Success Criteria · Verification +Strategy · Verification Method · Unique ID · Owner · Priority · Criticality · Risk` + +**Traceability wording.** 29148 §3.1.23 defines it as *"the derivation path (upward) and +allocation/flow-down path (downward)"* with parent/child terminology. **The standard does not use the +word "bidirectional"** — quote the upward/downward wording instead. + +--- + +## Step 5 — LLD: there is no standard. Say so, then use the menu. + +**Do not claim LLD has a canonical form.** IEEE Std 1016-2009 states outright: *"The demarcation +between architecture, high-level and detailed design varies from system to system and is beyond the +scope of this standard."* Its only template (Annex C) is **informative** and organised by +viewpoint/view pairs, not by the familiar section list. + +The nearest authority is IEEE 1016-2009's **twelve design viewpoints**, whose use IS normative where +applicable — §5.1: *"A design viewpoint defined in this clause shall be used in the SDD whenever +applicable to the design subject."* Treat it as a **menu, not a checklist**: + +`Context · Composition · Logical · Dependency · Information · Patterns · Interface · Structure · +Interaction · State dynamics · Algorithm · Resources` + +```toon +folklore[10]{section,backing}: + Data model,"[CONVENTION] IEEE 1016 Information viewpoint 5.6 · NASA data structures · DoD DID" + API contract / interfaces,"[CONVENTION] IEEE 1016 Interface 5.8 · ECSS 5.5 · DoD 4.3" + Sequence diagram,"[CONVENTION] IEEE 1016 Interaction 5.10 · ECSS 4.2 dynamic architecture" + State diagram,"[CONVENTION] IEEE 1016 State dynamics 5.11 · ECSS 4.3 behaviour" + Error handling,"[CONVENTION] DoD DI-IPSC-81435A 4.2 + 5.x(f)(5) exception and error handling" + Concurrency,"[CONVENTION] DoD DID 4.2 concurrent execution · IEEE 1016 Resources 5.13" + Capacity planning,"[CONVENTION] NASA NPR 7150.2 hardware utilization · DoD DID 4.1" + Idempotency,"[UNVERIFIED] NO primary-standard backing found — include only if the system needs it" + Observability,"[UNVERIFIED] NO primary-standard backing found — include only if the system needs it" + Migration / rollback,"[UNVERIFIED] NO primary-standard backing found — include only if the system needs it" +``` + +The last three are good engineering and belong in most real designs — just never cite a standard for +them, and never add a section the system does not actually need. + +**Stopping criterion** — the only operational one found, from ECSS-E-ST-40C Rev.1 (normative, free): +refine *"into lower levels containing software units that can be coded, compiled, and tested"*, and +specify interfaces precisely enough *"to allow coding without requiring further information."* +Depth is set by **codeability and testability**, not by page count. Past that point the code is the +source of truth and more LLD is waste. + +**HLD/LLD are not separate artifacts** in any standard checked — ECSS, DoD DI-IPSC-81435A and NASA +NPR 7150.2 all put architectural AND detailed design in ONE document, split by review milestone +(PDR vs CDR), not by document. Default to one design doc with sections. + +> **Domain caveat:** ECSS, DoD and NASA are safety-critical / defence-acquisition regimes. Borrowing +> their structure is **analogy, not compliance**. Never imply a project must satisfy them. + +--- + +## Step 6 — Anti-slop gate. Cut before shipping. + +Delete anything matching these. A shorter honest document beats a complete-looking empty one. + +```toon +cut[8]{smell,fix}: + "Section with no content specific to THIS system","Delete the section, not fill it" + "'robust/scalable/seamless/best-practice' with no number or mechanism","Name the mechanism or cut" + "Restating the template's own prompt text","Delete" + "A requirement nobody can test","Add Verification Success Criteria or drop it (C7)" + "Alternatives listed but never compared","Compare on the stated drivers, or drop to a lower tier" + "Risk table where every risk is MEDIUM/MEDIUM","Real exposure or delete the table" + "Numbers with no source (200ms, 1000 users)","Measure it, cite it, or mark [UNVERIFIED]" + "A diagram restating the text","Delete — a diagram must show what prose cannot" +``` + +**Mandatory in every doc T1+:** +- **Non-goals** — what this deliberately does NOT do +- **Drawbacks** — *"Why should we NOT do this?"* Empty here destroys the document's credibility +- **Impact of doing nothing** — the cost of standing still +- **Owner + date + state** — an unowned doc is a dead doc + +**[MEASURED]** Unowned docs decay by default: Google reported ~90% of GooWiki documents had **no +views or updates** in the months before deprecation, and documentation became the **#1 complaint** on +its internal developer surveys (*Software Engineering at Google*, ch.10). Caveat honestly — these are +self-reported internal figures with no published year, sample size or method, and era-specific to +before docs moved into source control. + +**Therefore ship docs INTO the repo beside the code they describe**, with an owner, and change them +in the same commit as the code. Google's six prescriptions — policy, source control, clear ownership, +review on change, tracked issues, periodic evaluation — are **[CONVENTION]**, explicitly not measured; +that chapter concedes freshness/accuracy tooling *"has still not caught up."* + +--- + +## Ordering is NOT settled + +Problem-first vs decision-first vs Amazon narrative: **no evidence survived in either direction** +across two research passes. Follow the house style if one exists; otherwise problem-first is a +defensible default. **Do not claim a standard requires an ordering** — the belief that the Rust RFC +template mandates problem-first was checked and did not hold up. + +## Do NOT encode these — checked and refuted + +```toon +refuted[4]{belief,status}: + "Google mandates a template-driven design-doc gate before major projects","Refuted 0-3" + "ISO/IEC/IEEE 42010 requires recording rationale for rejected alternatives","Refuted 0-3 — that convention is ADR/MADR/Rust RFC" + "The Rust RFC template mandates problem-first ordering","Refuted 1-2" + "adr.github.io names exactly four canonical ADR families","Refuted 0-3" +``` + +## Still unverified — do not cite as fact + +LLM-as-judge reliability figures (Cohen's κ gaps, position-bias numbers) and ALCE citation-quality +numbers were **never verified** across two research passes. Do not quote them. No benchmark for +AI-generated **technical documentation** quality was established to exist — the honest statement is +*"not established"*, not *"does not exist"*. + +## Related + +`rules/core/grounding-discipline.md` · `rules/core/prompt-validation.md` · `rules/core/verification.md` +· `skills/chain-of-verification` · `rules/workflow/workflow-deliverables.md` · `skills/documentation` +(runbooks) · `templates/decision-record.md` diff --git a/aura-frog/stats.json b/aura-frog/stats.json index cdddcfa2..24117cc5 100644 --- a/aura-frog/stats.json +++ b/aura-frog/stats.json @@ -1,9 +1,9 @@ { "version": "3.8.0", - "generated": "2026-08-20T04:12:23Z", + "generated": "2026-08-25T04:28:38Z", "components": { "agents": 15, - "skills": { "total": 42, "autoInvoke": 9 }, + "skills": { "total": 43, "autoInvoke": 10 }, "rules": { "total": 72, "core": 22, "agent": 20, "workflow": 30 }, "commands": 24, "hooks": 51, @@ -11,15 +11,15 @@ "scripts": 102 }, "performance": { - "alwaysLoadedLines": 4600, - "alwaysLoadedTokens": 31765, - "savingsPercent": 66, - "overheadPercent": 15 + "alwaysLoadedLines": 4921, + "alwaysLoadedTokens": 34745, + "savingsPercent": 64, + "overheadPercent": 17 }, "codebase": { "cjsLines": 24998, - "mdLines": 24959, - "shLines": 14721, - "totalFiles": 449 + "mdLines": 25369, + "shLines": 14722, + "totalFiles": 451 } } diff --git a/aura-frog/templates/confluence-page.md b/aura-frog/templates/confluence-page.md index 4cf212fd..f67cdba4 100644 --- a/aura-frog/templates/confluence-page.md +++ b/aura-frog/templates/confluence-page.md @@ -1,124 +1,100 @@ # Confluence Page Template -**This format is optimized for pasting into Confluence** +**Định dạng wiki-markup, dán thẳng vào Confluence.** Bản dành cho NGƯỜI đọc — bản AI đọc là +`TECH_SPEC.md` (TOON). Hai bản phải nói cùng một sự thật; lệch nhau là bug. + + --- -h1. [Feature Name] - Implementation Summary +h1. [Tên tính năng] + +*Ticket:* [JIRA-…] | *Ngày:* [YYYY-MM-DD] | *Owner:* [tên] | *Trạng thái:* ideation / discussion / published / committed / abandoned -*Ticket:* [JIRA-TICKET] | *Date:* [Date] | *Status:* ✅ Complete +{info} +*Đọc bởi:* [ai đọc, để ra quyết định gì] +*Trạng thái* theo vòng đời RFD của Oxide — _committed_ nghĩa là trang này mô tả hệ thống ĐANG CHẠY, +không phải dự định. Không có trạng thái _draft_: ra sớm kèm nhãn đúng còn hơn giữ lại chờ hoàn hảo. +{info} ---- -h2. Overview +h2. Vấn đề -Brief description of the feature and its purpose. +Hôm nay đang sai/thiếu cái gì, đo bằng gì. *Chưa nói giải pháp.* -h2. Implementation Details +h2. Non-goals -h3. Components Created +Cố tình KHÔNG làm: … -* ShareModal.tsx - Main modal component -* PlatformSelector.tsx - Platform selection UI -* useSharePost.ts - Sharing logic hook +h2. Quyết định -h3. Technical Stack +Chúng tôi sẽ … *(thể chủ động, dứt khoát)* -* React 18 -* TypeScript 5.0 -* Jest + React Testing Library -* React Query +h3. Các phương án đã cân nhắc ----- +|| Phương án || Ưu || Nhược || Vì sao chọn / loại || +| A | | | | +| B | | | | +| Không làm gì | | | | -h2. Test Results - -|| Metric || Value || Status || -| Total Tests | 53 | ✅ Pass | -| Coverage | 87% | ✅ Above target (85%) | -| Performance | 2.1s load time | ✅ Within SLA | +{warning} +*Vì sao KHÔNG nên làm việc này?* — Bỏ trống mục này thì tài liệu mất uy tín. Nêu nhược điểm thật. +{warning} ---- -h2. Architecture +h2. Thiết kế -{code:title=Component Structure} -ShareModal -├── PlatformSelector -│ ├── FacebookCard -│ ├── InstagramCard -│ └── LinkedInCard -└── ShareForm - ├── CaptionInput - └── SubmitButton -{code} +Kiến trúc, thành phần, luồng dữ liệu. Sơ đồ *chỉ* được có nếu nó cho thấy thứ văn xuôi không diễn +đạt nổi — sơ đồ chép lại đoạn văn bên trên thì xoá. ----- +h3. Interface / API -h2. API Endpoints +Với mỗi interface: kiểu, khuôn dạng, đơn vị, miền giá trị, ràng buộc thời gian, xử lý lỗi. +*Tiêu chí đủ:* người khác code được mà không phải hỏi thêm. -h3. POST /api/social/share +h3. Chế độ hỏng -*Request:* -{code:json} -{ - "platform": "facebook", - "content": "Post content", - "mediaUrl": "https://..." -} -{code} +|| Hỏng thế nào || Phát hiện bằng gì || Phản ứng || Ai được báo || +| | | | | -*Response:* -{code:json} -{ - "id": "post-123", - "status": "published", - "url": "https://facebook.com/..." -} -{code} +Nhớ cả lỗi *âm thầm* — exit 0 nhưng không làm gì, payload rỗng — không chỉ exception. ---- -h2. Deployment +h2. Tiêu chí thành công -*Environment:* Production -*Deployed:* [Date] -*Version:* [X.Y.Z] +Đo được, kèm cách đo. Chưa đo thì ghi `[UNVERIFIED] — sẽ đo bằng …` -h3. Deployment Checklist +h2. Kết quả kiểm thử -(/) Tests passing -(/) Code reviewed -(/) QA validated -(/) Documentation complete -(/) Deployed to production +|| Chỉ số || Giá trị || Nguồn || +| | | | ----- - -h2. Screenshots - -!screenshot1.png|thumbnail! -!screenshot2.png|thumbnail! +{note} +Chỉ điền số ĐÃ CHẠY THẬT. Bảng test toàn ✅ mà không ai chạy là thứ làm tài liệu mất giá trị nhanh nhất. +{note} ---- -h2. Documentation Links +h2. Rủi ro -* [Implementation Summary|link] -* [API Documentation|link] -* [User Guide|link] +|| Rủi ro || Phơi nhiễm thật || Giảm thiểu || +| | | | ----- +Mọi dòng đều MEDIUM/MEDIUM ⇒ xoá cả bảng, nó không nói gì. -h2. Team +h2. Câu hỏi chưa ngã ngũ -* *Developer:* [Name] -* *QA:* [Name] -* *Designer:* [Name] -* *PM:* [Name] +Cái gì cố tình để ngỏ, chốt ở đâu, khi nào. ---- -_Page created by [Aura Frog](https://github.com/nguyenthienthanh/aura-frog) -_Last updated: [Date]_ - +_Tạo bởi [Aura Frog|https://github.com/nguyenthienthanh/aura-frog] · Cập nhật: [YYYY-MM-DD]_ diff --git a/aura-frog/templates/decision-record.md b/aura-frog/templates/decision-record.md new file mode 100644 index 00000000..ccae7b9a --- /dev/null +++ b/aura-frog/templates/decision-record.md @@ -0,0 +1,119 @@ +# Decision Record — DR-NNN: [Tiêu đề ở thể khẳng định, vd "Dùng Postgres thay vì Mongo cho store đơn hàng"] + + + +**Trạng thái:** ideation | discussion | published | committed | abandoned + +**Ngày:** YYYY-MM-DD · **Owner:** [tên người chịu trách nhiệm cập nhật] + +--- + +## Bậc 1 — Y-statement (1 câu) + +Trong bối cảnh **[use case / user story]**, +đối mặt **[mối lo / lực cản]**, +chúng tôi chọn **[phương án]** +để đạt **[thuộc tính chất lượng]**, +chấp nhận **[điều đánh đổi]**. + +> ⚠️ Ô "chấp nhận" bắt buộc phải điền, nhưng điền ≠ đã cân nhắc thật. +> Nếu không nêu được một đánh đổi CỤ THỂ, quyết định này chưa chín — lên bậc 3. + +--- + +## Bậc 2 — ADR (Nygard, 5 mục) + +### Bối cảnh +Lực cản đang giằng co nhau là gì? Mô tả tình thế, **chưa nói giải pháp**. + +### Quyết định +Chúng tôi sẽ… *(thể chủ động, dứt khoát)* + +### Hệ quả +Cái gì trở nên dễ hơn, cái gì khó hơn **sau** quyết định này — cả tốt lẫn xấu. + +--- + +## Bậc 3 — MADR (thêm phần so sánh phương án) + +### Yếu tố dẫn dắt quyết định +- [Yếu tố 1 — vd ràng buộc vận hành, chi phí, kỹ năng đội] + +### Các phương án đã cân nhắc +1. **[Phương án A]** +2. **[Phương án B]** +3. **[Không làm gì]** ← luôn liệt kê, để lộ chi phí của việc đứng yên + +### Ưu / nhược từng phương án +**[Phương án A]** +- 👍 … +- 👎 … + +### Kết quả +Chọn **[phương án]**, vì [lý do bám vào yếu tố dẫn dắt ở trên]. + +**Confirmation:** làm sao BIẾT quyết định này được tuân thủ trong thực tế? +*(test, lint rule, review checklist, cảnh báo runtime — nêu cơ chế cụ thể, không nói "sẽ review kỹ")* + +**Người quyết định:** … · **Đã hỏi ý:** … · **Đã thông báo:** … + +--- + +## Bậc 4 — RFC (tách 2 tầng, theo mẫu Rust RFC) + +### Tóm tắt +Một đoạn. + +### Động cơ +Đang giải quyết vấn đề gì? Kết quả mong đợi là gì? + +### Giải thích tầng hướng dẫn (guide-level) +Trình bày như thể thứ này ĐÃ tồn tại và anh đang dạy một đồng nghiệp dùng nó. +Giới thiệu khái niệm mới, giải thích chủ yếu **bằng ví dụ**, nêu luôn thông báo lỗi mẫu / +cảnh báo deprecation / hướng dẫn migration nếu có. + +### Giải thích tầng tham chiếu (reference-level) +Phần kỹ thuật. Chi tiết đủ để: rõ nó tương tác với các thành phần khác ra sao, rõ sẽ hiện +thực thế nào, và **mổ xẻ các ca biên bằng ví dụ** — quay lại chính các ví dụ ở tầng trên. + +### Nhược điểm +**Vì sao KHÔNG nên làm việc này?** *(Bỏ trống mục này = tài liệu mất uy tín.)* + +### Lý lẽ và các phương án khác +Vì sao thiết kế này tốt nhất trong không gian các thiết kế khả dĩ? Đã cân nhắc những thiết kế +nào khác và vì sao loại? **Tác động của việc KHÔNG làm gì cả là gì?** + +### Tiền lệ +Ngôn ngữ / framework / hệ thống khác đã giải bài này ra sao? *(Được phép trả lời "không có" — +nhưng phải nói rõ là đã tìm.)* + +### Câu hỏi chưa ngã ngũ +Cái gì cố tình để ngỏ, sẽ chốt ở đâu và khi nào. + +--- + +## Nguồn của mẫu này + +| Bậc | Nguồn | Ghi chú | +|---|---|---| +| Y-statement | Olaf Zimmermann | 5 ô; trích trong paper MADR (CEUR-WS Vol-2072) | +| ADR | Michael Nygard, 2011 | Thứ tự gốc: Title, Context, Decision, Status, Consequences. **Bản gốc KHÔNG có mục alternatives** | +| MADR | github.com/adr/madr | Bản *minimal* vẫn giữ Considered Options. v3.0.0 đổi tên thành "Markdown Any Decision Records" | +| RFC | rust-lang/rfcs `0000-template.md` | Drawbacks / Rationale-and-alternatives / Prior-art là quy ước xã hội, **không có máy nào chặn PR thiếu mục** | +| Trạng thái | Oxide RFD 1 + IETF RFC 3 (1969) | 6 trạng thái, không có trạng thái "draft" | + +> **Mức bằng chứng:** đây là **quy ước ngành có nguồn sơ cấp**, không phải kết quả nghiên cứu đối chứng. +> Không có nghiên cứu nào chứng minh mẫu này cho ra quyết định tốt hơn. +> Thứ tự lập luận (problem-first / decision-first / narrative) hiện **không có bằng chứng** theo chiều nào — tự chọn theo nhà. diff --git a/aura-frog/templates/lld.md b/aura-frog/templates/lld.md index 9ea92978..d1b0732e 100644 --- a/aura-frog/templates/lld.md +++ b/aura-frog/templates/lld.md @@ -1,93 +1,93 @@ -# Low-Level Design (LLD) Template +# Design — [Tên hệ thống / tính năng] -**Feature:** [Feature Name] -**Date:** [Date] +**Trạng thái:** ideation | discussion | published | committed | abandoned +**Owner:** [ai chịu trách nhiệm cập nhật] · **Ngày:** YYYY-MM-DD +**Đọc bởi:** [ai đọc, để ra quyết định gì] ---- + --- -## Data Structures +## 1. Bối cảnh — cái gì đã có, cái gì đang đề xuất -```typescript -interface User { - id: string - name: string - email: string -} +> Tách bạch **[ĐANG CÓ]** và **[ĐỀ XUẤT]** ở mọi phát biểu. Trộn hai thứ này là nguồn gây hiểu sai +> số 1 của tài liệu thiết kế. Mọi phát biểu về code hiện tại phải trích `path/file.ts:120-134`. -interface Post { - id: string - userId: string - content: string - createdAt: Date -} -``` +## 2. Non-goals ---- +Tài liệu này **cố tình không** giải quyết: … -## API Endpoints - -### POST /api/posts -**Request:** -```json -{ - "content": "string", - "platform": "facebook" | "instagram" -} -``` - -**Response:** -```json -{ - "id": "string", - "status": "success" -} -``` +## 3. Thành phần & phụ thuộc +*(IEEE 1016 Composition 5.3 · Dependency 5.5)* ---- +## 4. Mô hình dữ liệu +*(Information viewpoint 5.6)* — schema, ràng buộc, index, chỉ số lượng dữ liệu dự kiến. -## State Management +## 5. Interface / API contract +*(Interface viewpoint 5.8)* — với mỗi interface: kiểu, khuôn dạng, đơn vị, miền giá trị, độ chính +xác, ràng buộc thời gian/khối lượng/thứ tự, xử lý lỗi và khôi phục, đồng bộ hoá. +**Tiêu chí đủ:** người khác code được mà không phải hỏi thêm. -- Local state: Modal open/close -- Global state: User data (Zustand) -- Server state: API data (React Query) +## 6. Luồng & trạng thái +*(Interaction 5.10 · State dynamics 5.11)* — sequence cho các đường đi chính; state machine nếu có +trạng thái tường minh. **Sơ đồ chỉ được tồn tại nếu nó cho thấy thứ văn xuôi không diễn đạt nổi.** ---- +## 7. Xử lý lỗi +Mỗi chế độ hỏng: phát hiện bằng gì → phản ứng ra sao → ai được báo → phục hồi thế nào. +Bao gồm cả lỗi **âm thầm** (kết quả rỗng, exit 0 nhưng không làm gì) — không chỉ exception. -## File Structure +## 8. Đồng thời & tranh chấp +Cái gì chạy song song, dùng chung tài nguyên gì, khoá ra sao, deadlock/race đã cân nhắc chưa. -``` -src/ -├── components/ -│ └── ShareModal.tsx -├── hooks/ -│ └── useSharePost.ts -└── api/ - └── shareApi.ts -``` +## 9. Tài nguyên & sức chứa +*(Resources viewpoint 5.13)* — CPU/RAM/đĩa/quota/rate limit. **Số phải có nguồn.** +Không có số đo thì ghi `[UNVERIFIED]` kèm cách đo, đừng bịa "1000 concurrent users". ---- +## 10. Vận hành *(giữ nếu hệ thống cần — KHÔNG có chuẩn nào bắt buộc)* +- **Idempotency** — chạy lại hai lần thì sao? +- **Observability** — hỏng lúc 3 giờ sáng thì nhìn vào đâu? +- **Migration / rollback** — quay lui bằng cách nào, dữ liệu đã ghi xử lý sao? -## Functions & Methods +> Ba mục này **không có chuẩn công bố nào chống lưng** — chúng là kỹ thuật tốt, không phải yêu cầu +> tuân thủ. Giữ vì hệ thống cần, đừng giữ vì template có. + +## 11. Truy vết requirement → thiết kế → test + +| Requirement | Thành phần | Test | +|---|---|---| +| REQ-001 | `src/…` | `…test.ts::…` | + +*(ECSS bắt buộc ma trận truy vết xuôi + ngược trong tài liệu thiết kế; đây là quy ước mượn từ miền +hàng không vũ trụ — **tương tự, không phải bắt buộc tuân thủ** với dự án thường.)* + +## 12. Rủi ro & điều chưa ngã ngũ +Rủi ro phải nêu **mức phơi nhiễm thật**. Bảng mà mọi dòng đều MEDIUM/MEDIUM thì xoá đi. + +--- -### handleSubmit() -**Purpose:** Submit post to selected platform -**Parameters:** `{ platform, content }` -**Returns:** `Promise` -**Logic:** -1. Validate input -2. Call API -3. Handle response -4. Show success/error +### Nguồn +IEEE Std 1016-2009 (12 design viewpoints; demarcation ngoài phạm vi) · ECSS-E-ST-40C Rev.1 Annex F +(SDD DRD, normative, tải tự do; tiêu chí dừng ở 5.5.2) · DoD DI-IPSC-81435A · NASA NPR 7150.2 SWE-111. +**Mức bằng chứng: [CONVENTION].** Không có nghiên cứu nào chứng minh cấu trúc này cho ra thiết kế +tốt hơn. ECSS/DoD/NASA thuộc miền an toàn-tới-tính-mạng và mua sắm quốc phòng — mượn cấu trúc của họ +là **loại suy, không phải tuân thủ**. diff --git a/aura-frog/templates/requirements.md b/aura-frog/templates/requirements.md index ab7ea868..249d0c8e 100644 --- a/aura-frog/templates/requirements.md +++ b/aura-frog/templates/requirements.md @@ -1,128 +1,116 @@ -# Requirements Document Template +# Requirements — [Tên tính năng] -**Feature:** [Feature Name] -**Ticket:** [JIRA-TICKET] -**Date:** [Date] -**Author:** PM Operations Orchestrator +**Trạng thái:** ideation | discussion | published | committed | abandoned +**Owner:** [ai chịu trách nhiệm] · **Ngày:** YYYY-MM-DD · **Ticket:** [JIRA-…] +**Đọc bởi:** [ai đọc, để ra quyết định gì] --- -## Overview +## Vấn đề -Brief description of the feature. +Cái gì đang sai/thiếu hôm nay, đo bằng gì? **Chưa nói giải pháp.** ---- - -## Functional Requirements - -### FR-001: [Requirement Name] -**Description:** User can... -**Priority:** HIGH/MEDIUM/LOW -**Acceptance Criteria:** -- [ ] Criterion 1 -- [ ] Criterion 2 - ---- +## Non-goals -## Non-Functional Requirements +Cố tình KHÔNG làm: … -### NFR-001: Performance -- Response time < 200ms -- Support 1000 concurrent users +## Thành công trông như thế nào -### NFR-002: Security -- Input validation -- API authentication +Tiêu chí **đo được**, kèm cách đo. Không có số đo thật thì ghi `[UNVERIFIED] — sẽ đo bằng …`, +đừng bịa ngưỡng. --- -## User Stories +## Yêu cầu -### US-001: As a [user type] -**I want to** [action] -**So that** [benefit] + -**Acceptance Criteria:** -- [ ] Criterion 1 -- [ ] Criterion 2 +### REQ-001 — [tên] ---- - -## Dependencies +> **Phát biểu:** [Chủ thể] **shall** [hành động] [điều kiện] [ràng buộc đo được]. -- API endpoints: [List] -- Third-party services: [List] -- Prerequisites: [List] +| Thuộc tính | Giá trị | +|---|---| +| Rationale | *vì sao cần — thiếu ô này thì C1 Necessary không kiểm được* | +| Trace to Parent | REQ-… hoặc nhu cầu gốc | +| Trace to Source | ai/tài liệu nào yêu cầu | +| Verification Method | test / phân tích / kiểm tra / demo | +| Verification Success Criteria | **đúng cái gì xảy ra thì coi là đạt** | +| Owner | | +| Priority · Criticality · Risk | | --- -## Assumptions - -- Assumption 1 -- Assumption 2 +## Cổng chất lượng — GtWR v4 (INCOSE, guidance) + +Kiểm **từng** requirement (C1–C9): + +| | Đạt? | +|---|---| +| C1 Necessary — bỏ đi thì có mất gì không | ☐ | +| C2 Appropriate — đúng mức trừu tượng | ☐ | +| C3 Unambiguous — chỉ hiểu được một nghĩa | ☐ | +| C4 Complete — không cần hỏi thêm để hiểu | ☐ | +| C5 Singular — **một** nghĩa vụ duy nhất | ☐ | +| C6 Feasible — làm được trong ràng buộc thật | ☐ | +| C7 Verifiable — **có cách chứng minh đạt** | ☐ | +| C8 Correct — mô tả đúng nhu cầu thật | ☐ | +| C9 Conforming — theo đúng mẫu câu đã thống nhất | ☐ | + +Kiểm **cả tập** (C10–C15): + +| | Đạt? | +|---|---| +| C10 Complete — tập đủ, không thiếu mảng nào | ☐ | +| C11 Consistent — không mâu thuẫn nhau | ☐ | +| C12 Feasible — khả thi **khi gộp lại** | ☐ | +| C13 Comprehensible — đọc cả tập vẫn hiểu | ☐ | +| C14 Able to be validated — chứng minh được là đúng thứ cần | ☐ | +| C15 Correct | ☐ | + +### Lint máy chạy được (tập con của R1–R42) + +- **R7** — cấm mơ hồ: *some, any, several, many, about, approximate* +- **R8** — cấm câu thoát: *as appropriate, as required, to the extent practical, if practicable* +- **R18–R23** — một `shall` một câu; cảnh báo `and`/`or` nối hai nghĩa vụ +- **R32** — `all/every/none` phải kèm phạm vi xác định +- **R33–R35** — số phải có đơn vị và dung sai +- **R36–R40** — cùng một khái niệm dùng cùng một từ xuyên suốt + +> ⚠️ Chỉ ~10–12 trong 42 rule kiểm được bằng máy. INCOSE §1.8 nói rõ công cụ NLP/AI *"do not address +> all the rules"* và việc thẩm định *"cannot be done without the project team doing the analysis +> manually."* **Đừng quảng cáo "42 kiểm tra tự động".** --- -## Constraints - -- Constraint 1 -- Constraint 2 - ---- +## Truy vết -## Risks +29148 §3.1.23 định nghĩa truy vết là *"the derivation path (upward) and allocation/flow-down path +(downward)"*, dùng thuật ngữ parent/child. **Chuẩn KHÔNG dùng chữ "bidirectional"** — trích đúng chữ +lên/xuống. -| Risk | Impact | Probability | Mitigation | -|------|--------|-------------|------------| -| Risk 1 | HIGH | MEDIUM | Mitigation plan | +| Requirement | Parent | Thiết kế | Test | +|---|---|---|---| +| REQ-001 | | | | --- -## Success Criteria +## Giả định · Ràng buộc · Phụ thuộc -- [ ] All acceptance criteria met -- [ ] 85%+ test coverage -- [ ] Performance benchmarks met -- [ ] Zero critical bugs +Mỗi mục ghi rõ **sai thì hỏng cái gì**. Giả định không có hệ quả thì không đáng viết. --- -## Initial Estimation - -### Story Points -**Total:** [X] story points (Fibonacci scale: 1, 2, 3, 5, 8, 13, 21) - -**Complexity Assessment:** [Trivial / Simple / Moderate / Complex / Very Complex / Extensive] - -**Breakdown:** -- Phase 1 (Understand + Design): [2-4] points -- Phase 2 (Test RED): [1-3] points -- Phase 3 (Build GREEN): [2-8] points -- Phase 4 (Refactor + Review): [1-3] points -- Phase 5 (Finalize): [0.5-1] points - -### Time Estimate -**Range:** [Y-Z] hours (~[W] days) - -**Breakdown:** -- Optimistic: [Y] hours -- Most Likely: [Y+X] hours -- Pessimistic: [Z] hours - -### Confidence Level -**Level:** [High / Medium / Low] - -**Reasoning:** -- Requirements clarity: [High/Medium/Low] -- Technical familiarity: [High/Medium/Low] -- Dependencies: [None/Few/Many] -- Unknowns: [None/Some/Many] - -### Effort Components -- **Effort (40%):** [How much work? How many files?] -- **Complexity (30%):** [How hard is the logic? Edge cases?] -- **Uncertainty (20%):** [How many unknowns? Familiar tech?] -- **Risk (10%):** [What can go wrong? How critical?] - -**📚 Reference:** Use Fibonacci scale (1, 2, 3, 5, 8, 13, 21) for estimation +### Nguồn +**ISO/IEC/IEEE 29148:2018** — chuẩn normative đang hiệu lực (thay IEEE 830-1998 qua bản 2011; bản +2011 cũng thay IEEE 1233 và 1362). Tách characteristics của requirement đơn lẻ (§5.2.5) khỏi +characteristics của **tập** (§5.2.6), cộng language criteria (§5.2.7) và attributes (§5.2.8). +*Nội dung clause trả phí — không trích tên như thể đã đọc từ chuẩn.* +**INCOSE GtWR v4** (INCOSE-TP-2010-006-04, 2023) — **guidance của hội, không phải chuẩn**; miễn phí; +là nguồn của C1–C15, R1–R42 và A1–A49 ở trên. +**Mức bằng chứng: [CONVENTION].** Không có nghiên cứu nào chứng minh requirement viết theo C1–C15 thì +ít lỗi hơn.