version: "1.0.0" name: designing-developer-portfolio-evidence description: Use when roadmap gaps need to become credible portfolio artifacts with explicit evidence contracts showing which capabilities a project must actually demonstrate.

Designing Developer Portfolio Evidence

Convert capability gaps into professional artifacts that can demonstrate several relevant skills at once. A project is useful evidence only when its observable contract is explicit.

Start from evidence gaps

Identify the target role, capability gaps, required evidence strength, and existing portfolio coverage. Prefer projects that exercise multiple related capabilities without becoming artificially broad.

Do not start from a fashionable stack and work backward to invented learning value.

Define the project brief

Specify:

• user or system problem;
• constraints and non-goals;
• meaningful technical decisions;
• required behaviors and failure cases;
• verification expectations;
• realistic completion boundary.

The artifact should be understandable without relying on the creator's narrative alone.

Define an evidence contract

For every target capability, state:

1. what observable behavior must exist;
2. what artifact proves it;
3. what verification strengthens the claim;
4. what would fail to demonstrate the capability.

Useful evidence may include tests, design rationale, architecture decisions, performance measurements, accessibility checks, security reasoning, debugging notes, deployment evidence, or change history.

Design for inspectability

Require a reviewer-friendly structure: clear README or case narrative, runnable or inspectable output when appropriate, source organization, verification instructions, and concise explanations of important decisions and trade-offs.

Map the completed artifact back to capabilities

After implementation, record only capabilities that the artifact actually demonstrates. Distinguish project existence from evidence quality, and preserve uncertainty where verification is weak.

Ownership boundaries

This method owns project/evidence briefs, evidence contracts, proof requirements, and mapping artifacts to capabilities. It never grants proficiency merely because a project exists and does not replace formal evaluation when the target criterion requires it.