Skip to content

Best Practices for Designing Tenka

"Tenka" (天下) refers metaphorically to the vision of a colossal project — literally "all under heaven" or "everything under the sky." It represents the complete functional horizon of your project.

Modeling requirements through User Stories and Acceptance Criteria ensures that both human developers and AI agents understand the goal, the context, and the definition of done.

Part I: Designing Good User Stories

A good user story follows the INVEST principle: Independent, Negotiable, Valuable, Estimable, Small, and Testable.

1. The Story Format

As a(n) <who>, I want <what>, so that <why>

  • Who: The persona or role. Be specific (e.g., "API Consumer" instead of "User").
  • What: The capability or feature.
  • Why: The underlying value or benefit.

2. Scope-local ID Rule

User Story IDs MUST follow the format US<us_num> (e.g., US101, US001). This ensures consistency and allows for easy reference.

3. Use Tags for Categorization

Use the tags field to categorize stories by functional area, technical domain, or priority.

  • Example: tags: [Security, Core, Functional]

4. Focus on Value

Avoid stories that describe technical tasks. Focus on the outcome.

  • Bad: "As a developer, I want to add a database column, so that I can store the user age."
  • Good: "As a researcher, I want to filter participants by age, so that I can analyze specific demographic groups."

Part II: Designing Good Acceptance Criteria (AC)

Acceptance Criteria are the source of truth for "Done." They should be unambiguous and testable.

1. The Given/When/Then Format

Daimyo supports a structured format for ACs:

  • Given: The initial context or precondition.
  • When: The action or event that triggers the behavior.
  • Then: The expected observable outcome.

2. Scope-local ID Rule

Acceptance Criteria IDs MUST follow the format AC<us_num>.<ac_num> (e.g., AC101.1, AC101.2). The first part must match the parent User Story number.

3. Use Tags for External Standards

Use tags to link ACs to external security standards, compliance requirements, or internal architectural mandates.

  • Example: tags: ["OWASP A03:2021", "GDPR"]

4. AC Best Practices

  • Testability: Every AC must be something you can prove with a test or manual check.
  • Outcome-oriented: Focus on what happens, not how it's implemented.
  • One behavior per AC: If an AC has an "and", consider splitting it.

Part III: Examples

Tenka Definition (tenka.yml)

tenka:
  US101:
    who: Registered User
    what: to reset my password via email
    why: I can regain access to my account if I forget it
    acs:
      AC101.1:
        given: a valid registered email address
        when: I request a password reset
        then: an email is sent with a unique, time-limited reset link
      AC101.2:
        given: an expired reset link
        when: I attempt to reset the password
        then: an error message is displayed and the password is not changed
  US102:
    who: Security Auditor
    what: a log of all password reset attempts
    why: I can detect and investigate potential brute-force attacks
    acs:
      AC102.1:
        then: every password reset request is logged with timestamp, IP, and status

Tenka Fulfillment (tenka.fulfillment.yml)

Fulfillment data tracks the actual progress. Remember that this file is local-only and should typically not be committed to shared repositories if it contains workspace-specific paths.

Best Practice: Use Sidecar Files

Use tenka.fulfillment.*.yml sidecar files to separate different types of validation data: - Keep automated results in the main tenka.fulfillment.yml (usually gitignored). - Store manual verdicts in a sidecar like tenka.fulfillment.manual.yml and commit it to git so the entire team shares the manual verification status.

# Example: tenka.fulfillment.manual.yml (Committed to Git)
tenka_fulfillment:
  AC101.1:
    - type: manual
      passed: true
      verdict: Verified email delivery and link validity using MailHog.
      timestamp: "2026-05-15T14:45:00Z"

# Example: tenka.fulfillment.yml (Gitignored)
tenka_fulfillment:
  AC101.1:
    - type: auto
      passed: true
      source: tests/integration/test_auth.py
      name: test_password_reset_email_sent
      timestamp: "2026-05-15T14:30:00Z"
  AC101.2:
    - type: auto
      passed: true
      source: tests/integration/test_auth.py
      name: test_expired_link_rejection
      timestamp: "2026-05-15T14:35:00Z"

Part IV: Managing Tenka in Scopes

1. Inheritance and Overrides

Use inheritance to define "Corporate" stories in a parent scope and "Project" specifics in a child scope.

  • Parent: Defines a general security requirement (US001).
  • Child: Overrides specific ACs to match the project's tech stack (e.g., specifying JWT instead of Session cookies in AC001.1).

2. Activation/Deactivation

Use active: false to keep stories in your vision while signaling they are not currently relevant or are deferred to a future milestone. Agents will ignore inactive stories by default.

Quick Reference Checklist

  • [ ] User Story ID follows US<us_num>.
  • [ ] Acceptance Criterion ID follows AC<us_num>.<ac_num>.
  • [ ] User stories follow the Role-Capability-Value format.
  • [ ] Stories are small enough to be completed in a single iteration.
  • [ ] ACs follow the Given/When/Then structure.
  • [ ] Each AC has at least one associated validation (auto or manual).
  • [ ] Fulfillment data reflects the current state of the local workspace.