Problems, Features, and Issues

8Vast tracks work through typed artifacts. Each type represents a different kind of work with its own lifecycle. They connect to each other — a problem leads to a feature, a feature breaks into issues, issues produce documents.

Problems

A problem is something that needs fixing. Not a task, not a ticket — a description of what's wrong.

Problems move through a lifecycle:

Raised -> Validated -> Evaluated -> InProgress -> Shipped -> Verified

• Raised — Someone noticed something wrong.
• Validated — The problem is confirmed. It's real, not a misunderstanding.
• Evaluated — The impact and urgency are assessed.
• InProgress — Someone is actively working on it.
• Shipped — The fix is deployed.
• Verified — The fix actually solves the problem.

Problems are the input to work. You don't start with a solution — you start with a problem. This matters because it forces investigation before implementation. A well-described problem often makes the solution obvious. A poorly described one leads to wasted effort.

When a workflow starts working on a problem, the problem's state transitions automatically. Starting a "fix" workflow moves the problem to InProgress. Completing it moves the problem to Shipped. You don't manually update statuses.

Features

A feature is something to build. Where a problem describes what's wrong, a feature describes what should exist.

Features have their own lifecycle:

Proposed -> Approved -> Building -> Shipped

• Proposed — Someone suggests building this.
• Approved — The decision is made: we're going to build it.
• Building — Active development.
• Shipped — It's live.

Features often come from problems. A bug report might reveal that the system needs a new capability, not just a fix. In that case, the problem leads to a feature. But features can also originate independently — someone has an idea for something new.

Features carry structured information: product requirements (what it should do), technical requirements (how it should be built), and story maps (how it breaks down into implementable pieces).

Issues

An issue is a work item. It's simpler than a problem or feature — it represents a discrete task with clear completion criteria.

Open -> InProgress -> Closed

Issues have acceptance criteria — specific, testable conditions that define "done." This isn't a description of the work; it's a checklist of what must be true when the work is complete.

Issues are often children of features. A feature like "add search to the dashboard" might break into issues: "build the search index," "add the search input component," "implement result ranking," "write integration tests." Each issue is independently completable.

Ideas

An idea is lighter than a problem or feature. It's a suggestion that hasn't been validated or committed to. Ideas get reviewed and sorted:

• Accepted — Worth pursuing. Graduates to a problem or feature.
• Rejected — Not worth pursuing. Documented with reasoning.
• Deferred — Worth pursuing later, but not now.

Ideas are the entry point. Not everything needs to start as a formal problem or feature. Sometimes you just have a thought. Ideas give that thought a place to live until you decide what to do with it.

Documents

Documents capture decisions, proposals, and specifications. They aren't work items — they're reference material produced by work.

Documents have purposes:

• Capture — Record something observed or learned.
• Propose — Suggest a course of action.
• Define — Specify how something should work.
• Explain — Describe how something works.
• Decide — Record a decision and its reasoning.
• Compare — Evaluate alternatives.

And states:

Draft -> InReview -> Approved

A feature's technical requirements are a document. A decision about which database to use is a document. Post-incident analysis is a document. The type gives structure; the state tracks progress.

How they connect

Artifacts link to each other. A problem might lead to a feature. A feature breaks into issues. Issues produce documents. Documents reference problems.

This forms a knowledge graph — you can trace from a bug report to the feature it spawned to the code that implemented it to the PR that shipped it. Nothing exists in isolation.

These connections happen naturally as you work. When a workflow starts from a problem and produces a feature, the link is created automatically. When an issue references a document, the link is recorded.

The graph is queryable. You can ask: "What problems led to this feature?" or "What issues are blocking this feature?" or "What decisions were made during this project?" The answers come from the connections between artifacts.

Workflows and artifacts

Workflows and artifacts work together through hooks. When a "fix" workflow begins, the problem it's addressing moves to InProgress. When the workflow completes, the problem moves to Shipped. When a "feature-planning" workflow produces a specification, a document is created and linked to the feature.

This means status updates happen as a side effect of doing work — not as a separate administrative task. The workflow does the work; the artifact tracks the state.