Methodological Values
The canonical values live in the Ezkey methodology corpus. This view keeps the operating tests visible: enough rigor to preserve judgment and traceability, but not enough ceremony to slow simple work.
Proportional rigor
Process weight follows uncertainty and risk, not habit or artifact size.
Test: what concrete risk does this extra step reduce?
Internal integrity
Lanes, skills, statuses, and artifacts connect without hidden session memory.
Test: can a later human or agent resume from here?
Explicit uncertainty
Statuses name what is known, what is open, and what confidence the artifact supports.
Test: does this output expose uncertainty instead of smoothing it over?
Readable state boundaries
Every skill has entry, exit, next-step, and fast-path boundaries.
Test: is the transition clear to a tired human and a cold agent?
Bidirectional traceability
Forward links show where work goes; backward links prove why it exists.
Test: can we navigate both to the source and to the durable outcome?
Earned permanence
Living documents, registries, checks, and skills must earn their maintenance cost.
Test: who updates this, when, and what if it stays stale?
End-to-End Workflow Lane A
Nine explicit phases with artifact outputs and exit criteria. Move to implementation as soon as direction, first cut, validation criteria, and non-blocking open questions are all settled — avoiding both premature coding and perpetual preparation.
Phase 1
Capture
Record the raw idea with clear intent and initial tags. Keep the first version short and expressive.
I-*
Done when: clear intent and tags assigned.
→
Phase 2
Triage
Clarify intent, user value, risk, and rough scope. Assign status, priority, progression markers, component tags.
I-* updated
Done when: scope and value understandable.
→
Phase 3
Challenge
Structured questioning pass ("Grill Me"). Surface assumptions, exceptions, error paths, non-goals.
I-* + open Qs
Done when: key risks and exceptions explicit.
→
Phase 4
Promote
Define the first vertical slice and expected evidence. Avoid adding preparation if direction is already clear.
TB-*
Done when: one vertical slice is testable.
→
Phase 5
Analyze & Design
Global analysis + component-specific analysis for each impacted boundary. Define responsibilities, contracts, validation, error behavior.
briefs + mappings
Done when: boundaries and decision points explicit.
→
Phase 6
Plan Tests
Select minimum and optional test layers: unit, functional, elective, operational, UI. Keep selection risk-based and cost-aware.
test plan slice
Done when: min test layers explicitly selected.
→
Phase 7
Gate
Apply methodology fit, analysis, design, implementation, and closeout gates. Verify mandatory checks before implementation.
gate report
Done when: mandatory quality checks pass.
→
Phase 8
Implement
Execute the plan in code and tests. Update docs and contracts in the same changeset. Controller changes imply contract review.
code + tests
Done when: evidence complete and gates green.
→
Phase 9
Close Out
Transition status, record evidence, separate corpus closure from active product backlog, and name residual risk.
status + traceability
Done when: closure is honest and resumable.
Artifact Types
All canonical artifacts use date+slug identifiers. No global counter lookup required. Identifiers are stable — never renamed after creation, never reused.
| Type | Identifier format | Location | Created at | Status lifecycle |
|---|---|---|---|---|
| V-* Vision note | V-YYYY-MM-DD-<slug>.md |
global/vision/ |
Capture / Triage | draft → under-review → promoted / archived |
| I-* Backlog idea | I-YYYY-MM-DD-<slug>.md |
global/backlog/ideas/ |
Capture | captured → triaged → incubating → ready → active → done / parked / archived / dropped |
| TB-* Tracer bullet | TB-YYYY-MM-DD-<slug>.md |
global/backlog/ |
Promote | draft → under-review → promoted / archived |
| R-* Retrofit slice | R-YYYY-MM-DD-<slug>.md |
global/legacy-retrofit/ |
Retrofit lane | captured → mapped → integrated → archived |
| plan Working plan | free name | plans/ or .cursor/plans/ |
Plan incubation lane | Non-canonical — materialized into V-*/I-*/TB-* |
| blitz Blitz scratch | _blitz-YYYY-MM-DD[-slug].md |
global/backlog/ |
Blitz intake | Active (_ prefix) → archived (no prefix, in blitz-archive/) |
| grill Grill session | <topic>-grill-me.md |
global/backlog/grill-sessions/ |
Challenge | open → resumed → complete, with post-decision notes when superseded |
| dec Methodology decision | YYYY-MM-DD-<slug>.md |
methodology/decisions/ |
Any — when a non-obvious methodology rule is adopted | Stable — never revised in place (supersede with new file) |
| RV Rich view | folder slug | <parent>/view/<slug>/index.html |
Any — when visual richness materially adds clarity | Companion to its Markdown parent — updated with it |
Parallel Lanes
Four lanes run alongside the main ideation-to-delivery flow. Any session may combine Lane A with one or more of these lanes as needed.
Lane B
Plan Incubation
- Create or evolve a working plan in
plans/ - Explore options and converge on direction (freeform)
- Materialize durable signal into V-*/I-*/TB-*
- Cross-link plan and canonical artifacts when useful
- Do not treat as retrofit unless genuinely historical
→ plan-incubation-workflow.md
Lane C
Legacy Retrofit
- Select a small source batch (historical plans, verbal history)
- Extract decisions, invariants, patterns, test signal
- Map into canonical docs
- Record a retrofit slice (R-*)
- Close with residual gaps and next action
→ legacy-retrofit-workflow.md
Lane D
Post-Delivery Re-entry
- Start from existing implemented behavior: enhancement, operator feedback, or apparent bug
- Classify pure local technical defect vs intent or scope change
- Fix local defects directly with bounded validation
- Re-enter at
TB-*,I-*, orV-*when intent changed - Continue through the normal delivery workflow from that re-entry point
→ workflow-overview.md
Lane E
Methodology Feedback
- Capture friction, ambiguity, or a proposed improvement in the method itself
- Record the decision in
methodology/decisions/ - Preserve short verbatim source signal when exact wording matters
- Update only the smallest methodology surfaces that must change
- Close with the evidence that will show whether the change helped
→ decisions/README.md
Collaboration Context
Not a lane — a cross-cutting modifier. These rules apply on top of Lanes A, B, C, and D whenever collaboration happens across parallel Git branches or worktrees. Lane E is usually handled single-branch because it changes the methodology itself.
Cross-cutting · applies to Lanes A, B, C, D
When two developers (or one developer across two worktrees) work simultaneously, classic ordinal naming creates merge-time collisions. The collaboration context resolves this without coordination overhead, by making artifact names self-sufficient through date+slug identifiers and deferring shared indexes to post-merge.
Date+slug IDs mandatory
No counter lookup, no contention across branches.
Create artifacts freely on branch
V-*, I-*, TB-*, R-* — no cross-branch coordination needed.
Blitz slug required
On a feature branch, topic slug is chosen at session start — not the ordinal fallback.
Defer index updates
backlog/index.md, vision/product-orientation-notes.md — update post-merge on main.
Index reconciliation at merge
Run a reconciliation pass when the branch lands on
main.
→ multi-branch-workflow.md
Naming Conventions
Stable, collision-resistant identifiers across all branches and worktrees.
Legacy NNNN artifacts are never renamed.
| Artifact | Active filename | Archived / final | Key rule |
|---|---|---|---|
| Vision note | V-YYYY-MM-DD-<slug>.md |
Same (stable) | Never renamed after creation |
| Backlog idea | I-YYYY-MM-DD-<slug>.md |
Same (stable) | Never renamed after creation |
| Tracer bullet | TB-YYYY-MM-DD-<slug>.md |
Same (stable) | Never renamed after creation |
| Retrofit slice | R-YYYY-MM-DD-<slug>.md |
Same (stable) | Never renamed after creation |
| Blitz — feature branch | _blitz-YYYY-MM-DD-<slug>.md |
blitz-archive/blitz-YYYY-MM-DD-<slug>.md |
Slug required; chosen at session start |
| Blitz — main / single-branch | _blitz-YYYY-MM-DD[-N].md |
blitz-archive/blitz-YYYY-MM-DD[-N].md |
Ordinal accepted if theme unclear at start |
| Grill session | <topic>-grill-me.md |
Same | Must include "Resume at" control block |
| Methodology decision | YYYY-MM-DD-<slug>.md |
Same | Under methodology/decisions/ |
| Rich view | <parent>/view/index.html or <parent>/view/<slug>/index.html |
Same | Self-contained HTML; linked from parent Markdown |
Bidirectional Traceability
The workflow is not only a forward pipeline. Closeout and audit must also prove where an artifact came from, what canon absorbed it, and whether later decisions changed its meaning.
Source
Raw idea, blitz archive, working plan, historical plan, or verbal briefing.
→
Materialization
V-*, I-*, R-*, or documented drop with rationale.→
Challenge
Grill session, open questions, decision pressure points, status alignment.
→
Canon
ADR, methodology decision, policy output, component pack, or traceability matrix.
→
Closeout
Status transition, evidence, residual risk, next action, or supersession.
Backward audit Can this closeout navigate back to the source and materialized artifacts?
Status alignment Do indexes and artifact metadata agree after grill, retrofit, or implementation?
Current truth Are post-decision notes and supersession links present when history changed?
Honest closure Is corpus integration separated from still-active product backlog work?
Skill Boundary Contracts
Each skill answers the same four questions: enter when, exit when, call next, and not needed
when. The canonical skill text lives under .cursor/skills/; this table is the
fast navigation surface.
| Skill | Enter when | Exit when | Call next | Not needed when |
|---|---|---|---|---|
vision-intake |
Strategic direction, product intent, or early feature ideas arrive. | Durable direction is captured as V-* or initial I-* with next step. |
backlog-triage or grill-me |
The idea is already a bounded implementation slice. |
backlog-triage |
An I-* exists or a vision note has actionable scope. |
Scope, non-scope, priority, status, tags, risks, and posture are explicit. | grill-me or tracer-bullet-promote |
The item is still pure orientation or already fully scoped. |
grill-me |
Assumptions, exception paths, lifecycle effects, or boundary risks need pressure. | Risks, open questions, decision pressure points, and clarifications are explicit. | Triage, tracer-bullet promotion, or component design. | The change is low-risk, bounded, and has known validation criteria. |
plan-incubation |
The operator starts from a current-session working plan. | Durable signal is classified for V-*, I-*, TB-*, principle adoption, or mix. |
Vision intake, backlog triage, or tracer-bullet promotion. | The source is historical retrofit input or a direct implementation task. |
tracer-bullet-promote |
An I-* is ready and needs a bounded vertical slice. |
The TB-* has posture, scope, boundaries, exclusions, and evidence criteria. |
component-design-pack and test-strategy-planner |
The item lacks direction, or the change is a tiny code/doc fix. |
component-design-pack |
A scope touches component boundaries, mappings, validations, or error behavior. | Impacted components have responsibilities, contracts, tests, and doc impact named. | test-strategy-planner, then quality-gatekeeper |
The change is local, internal, and not observable at a boundary. |
test-strategy-planner |
A change has known risks and needs explicit test-layer selection. | Minimum, optional, deferred, and rejected test layers are justified. | quality-gatekeeper, then traceability after evidence changes. |
The change is purely editorial. |
quality-gatekeeper |
Work moves from analysis to execution, or execution to closeout. | The gate returns go or no-go with blockers and follow-up actions. |
Implementation after go, or targeted repair after no-go. |
The task is trivial and has no analysis, contract, test, or traceability impact. |
traceability-sync |
Feature status, behavior, specs, tests, or validation evidence changed. | Global and component traceability documents reflect current evidence and gaps. | closeout |
No observable behavior, contract, status, or validation evidence changed. |
closeout |
A tracer bullet, feature slice, blitz integration, retrofit slice, or cycle is ending. | Status transitions, evidence, deferred work, residual risks, and next actions are explicit. | No next skill by default; reopen named follow-up work only. | The work is still actively changing or required evidence is unavailable. |
legacy-plan-miner |
Historical plans, verbal history, or ad hoc implementation history contain reusable signal. | Reusable signal is extracted with confidence and source type. | retrofit-curator |
The source is a current-session working plan. |
retrofit-curator |
Mined historical signal needs mapping into canonical destinations. | The R-* records mappings, canonical updates, residual gaps, and index status. |
traceability-sync or closeout |
No reusable signal exists, or the source already lives in current canon. |
Rich Views
HTML companions to Markdown source documents, created when visual richness materially improves clarity and conceptual alignment between human and AI collaborators. The base methodology remains Markdown-first — rich views are deliberate supplements, not replacements.
When to create a rich view
- Complex entity relationships — multiple interdependent entity types with lifecycle interactions that are hard to follow in prose or tables alone.
- State machines & lifecycle governance — state transitions, activation/deactivation rules, parent-chain propagation across entity types.
- Cryptographic or protocol flows — multi-actor flows with key material transit, synchronization windows, and sequencing constraints where a diagram anchors understanding.
- High-impact architectural decisions — cross-cutting decisions with visual complexity that benefits from a durable graphical anchor.
- The methodology itself — the process and artifact system benefits from a visual reference accessible to both humans and AI agents at session start.
Folder and linking convention
| Context | Path pattern | Link from Markdown parent |
|---|---|---|
| Methodology (this file) | product-docs/methodology/view/index.html |
[Rich view](view/index.html) |
| Global docs (e.g. Lifecycle Governance) | docs/view/<slug>/index.html |
[Rich view](view/<slug>/index.html) |
| Component-level | product-docs/components/<comp>/view/index.html |
[Rich view](view/index.html) |
Design principles
- Self-contained — no external CDN dependencies. Embed all styles and SVG inline.
- Sober palette — information first. Color is used for distinction, not decoration.
- Linked from the parent Markdown — the source document carries a clear reference to the rich view.
- Updated in the same changeset — when the parent document changes, the rich view is updated alongside it.
- Single
index.htmlper view folder; additional files only when navigation genuinely adds value for the specific topic.