Product Spec Harness
GuidesHướng dẫn
HomeTrang chủ › GuidesHướng dẫn › Spec hierarchyCây spec
The backbone of every spec — Vision to StoryXương sống của mọi spec — từ Vision đến Story

Spec HierarchyPhân cấp Spec

5 levels · parent-scoped IDs

Every spec is a single directed tree: one Vision anchors one BRD which spawns many PRDs, each PRD owns Epics, each Epic owns Stories. IDs encode lineage — a script can resolve any Story all the way up to its BRD goal without reading prose. Frontmatter is always the source of truth; the LLM never infers structure from headings.Mọi spec là một cây có hướng duy nhất: một Vision neo một BRD, BRD sinh ra nhiều PRD, mỗi PRD sở hữu Epic, mỗi Epic sở hữu Story. ID mã hóa dòng dõi — script có thể giải ngược bất kỳ Story nào lên đến mục tiêu BRD mà không cần đọc văn bản. Frontmatter luôn là nguồn sự thật; LLM không bao giờ suy ra cấu trúc từ tiêu đề.

THE FIVE LEVELSNĂM CẤP ĐỘ

Vision → BRD → PRD → Epic → StoryVision → BRD → PRD → Epic → Story

Each level has a single, non-overlapping job. A product owner authors each node in conversation with the skill; the skill never invents scope or personas.Mỗi cấp có một nhiệm vụ duy nhất, không chồng chéo. Product owner soạn từng node trong cuộc hội thoại với skill; skill không bao giờ tự đặt phạm vi hay personas.

VISION North-star + personasĐịnh hướng dài hạn + personas One narrative statement of what the product is, who it serves, and what core value it delivers. Home for persona labels that all downstream nodes inherit. One per product.Một tuyên bố mô tả sản phẩm là gì, phục vụ ai, và giá trị cốt lõi là gì. Nơi lưu nhãn persona mà tất cả node bên dưới kế thừa. Mỗi sản phẩm có đúng một Vision.
BRD Business goals + success metricsMục tiêu kinh doanh + chỉ số thành công A single Business Requirements Document that lists measurable goals (BRD-G1, BRD-G2, …). Each goal carries ≥1 metric slug. PRDs must link back to at least one BRD goal. One per product.Một tài liệu yêu cầu nghiệp vụ duy nhất liệt kê các mục tiêu đo lường được (BRD-G1, BRD-G2, …). Mỗi mục tiêu cần ít nhất 1 metric slug. PRD phải liên kết về ít nhất một mục tiêu BRD. Mỗi sản phẩm có đúng một BRD.
PRD Feature-area scope + requirementsPhạm vi tính năng + yêu cầu One Product Requirements Document per feature area (e.g. PRD-AUTH, PRD-CATALOG). Declares scope, moscow, personas, and links to its BRD goals. Many PRDs per BRD.Một tài liệu yêu cầu sản phẩm cho mỗi vùng tính năng (ví dụ PRD-AUTH, PRD-CATALOG). Khai báo scope, moscow, personas và liên kết về mục tiêu BRD. Mỗi BRD có nhiều PRD.
EPIC A deliverable slice of a PRDMột lát bàn giao được của PRD A coherent chunk of work that delivers standalone value. Owns a target_date, horizon, and optional risks. ID is parent-scoped: PRD-AUTH-E1, PRD-AUTH-E2. Many epics per PRD.Một khối công việc có giá trị bàn giao độc lập. Sở hữu target_date, horizon và risks tùy chọn. ID có phạm vi cha: PRD-AUTH-E1, PRD-AUTH-E2. Mỗi PRD có nhiều epic.
STORY Atomic unit with acceptance criteriaĐơn vị nguyên tử kèm tiêu chí chấp nhận The build team's direct input. Must carry ≥1 acceptance criterion in Given-When-Then form. ID is parent-scoped: PRD-AUTH-E1-S1. Many stories per epic.Đầu vào trực tiếp cho đội phát triển. Phải có ít nhất 1 tiêu chí chấp nhận dạng Given-When-Then. ID có phạm vi cha: PRD-AUTH-E1-S1. Mỗi epic có nhiều story.

The full acme-shop tree, rendered from --viz tree --format ascii:Cây acme-shop đầy đủ, render từ --viz tree --format ascii:

visualize.py --root examples/acme-shop --view tree --format ascii
PRODUCT: Acme Shop
  [goal:BRD-G1] Onboard 100 boutique brands in 12 months · approved
    [prd:PRD-CATALOG] Catalog & Storefront · approved
      [epic:PRD-CATALOG-E1] Catalog Management Epic · approved
        [story:PRD-CATALOG-E1-S1] Add and publish a product · approved
        [story:PRD-CATALOG-E1-S2] Track inventory per variant · approved
      [epic:PRD-CATALOG-E2] Brand Storefront Epic · approved
        [story:PRD-CATALOG-E2-S1] Browse the catalog · approved
        [story:PRD-CATALOG-E2-S2] Product detail page · approved
    [prd:PRD-CHECKOUT] Checkout · approved
      [epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
        [story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
        [story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
      [epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
        [story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
        [story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
      [epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
        [story:PRD-CHECKOUT-E3-S1] Track order status · approved
  [goal:BRD-G2] Achieve 80% 90-day repeat-purchase rate · approved
    [prd:PRD-CHECKOUT] Checkout · approved
      [epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
        [story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
        [story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
      [epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
        [story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
        [story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
      [epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
        [story:PRD-CHECKOUT-E3-S1] Track order status · approved
    [prd:PRD-FANCRM] Fan-CRM · review
      [epic:PRD-FANCRM-E1] Fan Messaging Epic · review
        [story:PRD-FANCRM-E1-S1] Send a fan broadcast · draft
        [story:PRD-FANCRM-E1-S2] Reply inbox · draft
      [epic:PRD-FANCRM-E2] Audience Segments Epic · draft
        [story:PRD-FANCRM-E2-S1] Segment by purchase history · draft
  [goal:BRD-G3] Reach $2M GMV in the first year · approved
    [prd:PRD-ANALYTICS] Brand Analytics · draft
      [epic:PRD-ANALYTICS-E1] Revenue Dashboard Epic · draft
        [story:PRD-ANALYTICS-E1-S1] View revenue over time · draft
        [story:PRD-ANALYTICS-E1-S2] Export report CSV · draft
    [prd:PRD-CATALOG] Catalog & Storefront · approved
      [epic:PRD-CATALOG-E1] Catalog Management Epic · approved
        [story:PRD-CATALOG-E1-S1] Add and publish a product · approved
        [story:PRD-CATALOG-E1-S2] Track inventory per variant · approved
      [epic:PRD-CATALOG-E2] Brand Storefront Epic · approved
        [story:PRD-CATALOG-E2-S1] Browse the catalog · approved
        [story:PRD-CATALOG-E2-S2] Product detail page · approved
    [prd:PRD-CHECKOUT] Checkout · approved
      [epic:PRD-CHECKOUT-E1] Sign-In + Address Epic · approved
        [story:PRD-CHECKOUT-E1-S1] Magic-link sign-in at checkout · approved
        [story:PRD-CHECKOUT-E1-S2] Saved addresses for returning shoppers · approved
      [epic:PRD-CHECKOUT-E2] Stripe Payment Epic · approved
        [story:PRD-CHECKOUT-E2-S1] Pay with Stripe at checkout · approved
        [story:PRD-CHECKOUT-E2-S2] Order confirmation email · approved
      [epic:PRD-CHECKOUT-E3] Order Tracking Epic · approved
        [story:PRD-CHECKOUT-E3-S1] Track order status · approved
  [goal:BRD-G4] Keep average brand payout latency under 3 days · approved
    [prd:PRD-ANALYTICS] Brand Analytics · draft
      [epic:PRD-ANALYTICS-E1] Revenue Dashboard Epic · draft
        [story:PRD-ANALYTICS-E1-S1] View revenue over time · draft
        [story:PRD-ANALYTICS-E1-S2] Export report CSV · draft
    [prd:PRD-PAYOUTS] Brand Payouts · approved
      [epic:PRD-PAYOUTS-E1] Automated Payouts Epic · approved
        [story:PRD-PAYOUTS-E1-S1] Scheduled payout run · approved
        [story:PRD-PAYOUTS-E1-S2] Payout statement export · approved
  [goal:BRD-G5] Launch native mobile shopping by year 2 · review
    [prd:PRD-MOBILE] Native Mobile Shopping · draft
      [epic:PRD-MOBILE-E1] Mobile App Shell Epic · draft
        [story:PRD-MOBILE-E1-S1] Mobile browse and buy · draft
  [goal:BRD-G6] Scale to 500 brands with cross-brand discovery (year 3) · draft
    [prd:PRD-DISCOVERY *] Cross-Brand Discovery · draft
      [epic:PRD-DISCOVERY-E1 *] Cross-Brand Discovery Epic · draft
        [story:PRD-DISCOVERY-E1-S1 *] Personalized discovery feed · draft
— 42 nodes · 6 goals · 7 prds · 11 epics · 18 stories · 0 findings
HOW IDS ARE FORMEDCÁCH HÌNH THÀNH ID

Parent-scoped, lineage-readable, no central allocatorPhạm vi cha, đọc được dòng dõi, không cần bộ cấp phát trung tâm

Every ID encodes its full ancestry. A script that reads PRD-AUTH-E1-S1 knows the story belongs to epic E1, which belongs to PRD-AUTH, which belongs to the BRD — without opening a single file.Mỗi ID mã hóa toàn bộ tổ tiên. Script đọc PRD-AUTH-E1-S1 biết ngay story thuộc epic E1, epic thuộc PRD-AUTH, PRD thuộc BRD — mà không cần mở bất kỳ file nào.

ArtifactTài liệu PatternMẫu ExampleVí dụ Slug rulesQuy tắc slug
BRD goalMục tiêu BRD BRD-G<n> BRD-G1, BRD-G2 Next free integer in BRDSố nguyên kế tiếp trong BRD
PRD PRD-<SLUG> PRD-AUTH, PRD-BILLING Uppercase, ≤16 chars; regex ^[A-Z][A-Z0-9-]{0,15}$Chữ hoa, ≤16 ký tự; regex ^[A-Z][A-Z0-9-]{0,15}$
Epic PRD-<SLUG>-E<n> PRD-AUTH-E1, PRD-AUTH-E2 Next free integer within that PRDSố nguyên kế tiếp trong PRD đó
Story PRD-<SLUG>-E<n>-S<n> PRD-AUTH-E1-S1 Next free integer within that epicSố nguyên kế tiếp trong epic đó
Decision DEC-<n> DEC-1, DEC-2 Globally monotonic; never reusedToàn cục đơn điệu tăng; không bao giờ tái sử dụng
Outcome OUT-<n> OUT-1, OUT-2 Globally monotonic; never reusedToàn cục đơn điệu tăng; không bao giờ tái sử dụng
📌
The slug is permanent. Renaming a PRD does not update existing epic/story IDs — they keep the original lineage. IDs and frontmatter keys always stay English even when the content language is Vietnamese.Slug là cố định. Đổi tên một PRD không cập nhật ID của epic/story hiện có — chúng giữ nguyên dòng dõi gốc. ID và khóa frontmatter luôn là tiếng Anh kể cả khi ngôn ngữ nội dung là tiếng Việt.
FRONTMATTER IS SOURCE OF TRUTHFRONTMATTER LÀ NGUỒN SỰ THẬT

Parse YAML — never infer structure from headingsPhân tích YAML — không bao giờ suy cấu trúc từ tiêu đề

This is Operating Principle 1. Every artifact carries a YAML frontmatter block at the top of the file. Scripts parse it exclusively. The prose body below the frontmatter is for human readers only — the skill never reads headings to decide what type of artifact something is or what its status is.Đây là Nguyên lý Vận hành thứ 1. Mỗi tài liệu đều có khối YAML frontmatter ở đầu file. Script chỉ phân tích phần này. Phần văn xuôi bên dưới frontmatter chỉ dành cho người đọc — skill không bao giờ đọc tiêu đề để xác định loại hoặc trạng thái của tài liệu.

Universal frontmatter fieldsTrường frontmatter chung

id type status draft|review|approved lang en|vi owner created updated version

Parent-link fieldsTrường liên kết cha

story → epic: PRD-AUTH-E1 epic → prd: PRD-AUTH prd → brd_goals: [BRD-G1]

A missing referent is a dangling_link error at validate time.Một tham chiếu không tồn tại là lỗi dangling_link khi validate.

Anti-rationalization: "The heading says APPROVED" is not evidence. Only status: approved in frontmatter counts. "The file tree shows graph state" is not evidence. Run the scripts first.Chống tự hợp lý hóa: "Tiêu đề ghi APPROVED" không phải bằng chứng. Chỉ có status: approved trong frontmatter mới được tính. "Cây file thể hiện trạng thái đồ thị" không phải bằng chứng. Chạy script trước.
SCOPE & CORE VALUEPHẠM VI & GIÁ TRỊ CỐT LÕI

Every node declares its scope — PO decides, never the skillMỗi node khai báo phạm vi — PO quyết, không bao giờ là skill

Scope is the PO's call. The skill surfaces the question during the interview and records the answer in frontmatter. It never assumes or defaults a scope. The three values are:Phạm vi là quyết định của PO. Skill đặt câu hỏi trong buổi phỏng vấn và ghi lại câu trả lời trong frontmatter. Skill không bao giờ giả định hoặc mặc định phạm vi. Ba giá trị là:

ValueGiá trị MeaningÝ nghĩa LLM checkKiểm tra LLM
in In scope for the current releaseTrong phạm vi phát hành hiện tại Core-value alignment scored: aligned / weak / offChấm điểm tương thích giá trị cốt lõi: aligned / weak / off
out Explicitly out of scope; excluded from most viewsRõ ràng ngoài phạm vi; bị loại khỏi hầu hết các khung nhìn ——
core-value PO's claim: this is part of the stated core value propositionTuyên bố của PO: đây là phần của đề xuất giá trị cốt lõi đã khai báo Highest alignment bar; competitive-drift check applies when ≥2 competitors trackedNgưỡng tương thích cao nhất; kiểm tra competitive-drift áp dụng khi theo dõi ≥2 đối thủ
⚖️
GATE-NEVER-ASSUME: the skill never sets scope: core-value on the PO's behalf. It also never defaults scope when the PO is ambiguous — it asks. Scope is PO's call, non-negotiable. GATE-NEVER-ASSUME: skill không bao giờ đặt scope: core-value thay cho PO. Skill cũng không mặc định scope khi PO chưa rõ — nó hỏi. Phạm vi là quyết định của PO, không thương lượng được.
How specs are validated →Cách validate spec → product-spec skillSkill product-spec
← PrevTrướctelemetrytelemetryNextSau →ValidationKiểm tra