ES-101 Evidence¶
Purpose¶
This page defines the evidence expected from ES-101.
Vision evidence is the first durable project record. It explains why the project exists, what problem it addresses, who it affects, what is in scope, and how success will be recognized.
Required evidence¶
ES-101 requires the following evidence under:
docs/vision/
| Artifact | Evidence Purpose |
|---|---|
problem_statement.md |
Establishes the operational or engineering problem. |
vision_statement.md |
Defines the intended system direction and purpose. |
stakeholders.md |
Identifies users, affected parties, operators, reviewers, and governance stakeholders. |
scope.md |
Defines what is included, excluded, deferred, or prohibited. |
assumptions.md |
Records material assumptions requiring awareness or validation. |
success_metrics.md |
Defines how success may be evaluated. |
vision_readiness_summary.md |
Summarizes readiness to begin ES-102. |
Evidence quality expectations¶
Each artifact should be:
- specific enough to guide later engineering work;
- concise enough to be reviewed;
- explicit about uncertainty;
- aligned with the other vision artifacts;
- stored in the repository;
- written for future readers, not only the current team.
What counts as sufficient evidence¶
Vision evidence is sufficient when a reviewer can answer:
- What problem is the project addressing?
- Who is affected?
- Why does the problem matter?
- What is the system intended to improve?
- What is in scope?
- What is out of scope?
- What assumptions are being made?
- What would count as success?
- What questions remain open?
- Is ES-102 ready to begin?
What does not count¶
The following are not sufficient ES-101 evidence:
- a slide deck stored outside the repository;
- a vague one-sentence goal;
- a solution name without problem context;
- stakeholder names without roles or concerns;
- success criteria that cannot be evaluated;
- assumptions hidden in conversation;
- AI-generated vision text that has not been reviewed.
Relationship to ES-102¶
ES-102 will use ES-101 evidence to define requirements and constraints.
Weak vision evidence creates weak requirements.
For example:
| Weak ES-101 Evidence | ES-102 Consequence |
|---|---|
| Vague problem | Requirements become feature guesses. |
| Missing stakeholders | Requirements omit affected parties. |
| Unclear scope | Requirements expand uncontrollably. |
| Hidden assumptions | Requirements embed unverified claims. |
| Vague success metrics | Testing and release readiness become subjective. |
AI-use evidence¶
ES-101 does not require a formal AI-use log unless your project, course, organization, or governance context requires it.
However, if AI materially shaped the vision artifacts, record that fact in the relevant artifact or in an AI-use record if your repository uses one.
Minimum recommended statement:
AI assistance was used to draft or critique this artifact. The engineering team reviewed and revised the content and remains responsible for the final claims.
Review evidence¶
For individual work, review may be self-review.
For team work, review should include at least one other person.
For classroom work, review may occur through peer review, instructor review, or team discussion.
Recommended review questions:
- Is the problem stated without assuming the solution?
- Are stakeholders complete enough for requirements work?
- Is scope specific enough to constrain decisions?
- Are assumptions visible?
- Are success metrics meaningful?
- Are open questions identified?
Common pitfall¶
Do not confuse artifact completion with evidence quality.
A filled-in template may still be weak evidence if it is vague, inconsistent, or unsupported.
Engineering insight¶
Evidence is useful when it can be challenged.
If nobody can review, question, or verify the artifact, it is not yet strong engineering evidence.