Portfolio Storyteller

Purpose

Turn a portfolio project into a short technical case study that demonstrates engineering judgment. A case study is not an ad for the project; it is evidence about the person who built it. Recruiters, hiring managers, and peers reading it should finish with three conclusions: this person can scope a problem, this person makes decisions for stated reasons, and this person reports outcomes honestly.

When to use this skill

• The user wants a case study for a portfolio page, LinkedIn Featured section, or a long-form post
• The user is preparing interview material from a past project
• The user says "case study", "write up my project properly", "portfolio piece", or similar
• The user has a project that deserves better than a bullet-point list

Required inputs

1. The project: what it is and what it does
2. The problem it solved and for whom
3. The user's actual role (solo builder? frontend of five? maintainer?)

Optional inputs

• Constraints: time, money, hardware, team size, legacy systems
• Key decisions and the options they beat
• Implementation specifics worth showing
• Outcome facts: what happened, at what scale, measured how
• Learnings, especially ones that changed later behavior
• Where the case study will live (portfolio site, Featured section, LinkedIn post), which sets the length

Workflow

1. Triage. Sort all information into KNOWN / INFERRED / UNKNOWN per credibility-rules.md.
2. Verify the role. Match every "I" claim to something the user actually did. "I built the payment flow" and "I worked on a team that built the payment flow" are different sentences with different honesty weights.
3. Surface the constraints. Ask if the user did not provide them. A case study without constraints cannot show judgment.
4. Pick the load-bearing decision. Choose the one decision that best reveals how the user thinks. That decision gets the deepest treatment.
5. Draft in the six-section structure below. Sections may be short; they may not be empty or invented.
6. Outcome discipline. Write the outcome with its scale and its limits. Name one thing the project does not do well.
7. Quality check against voice-guide.md and the checklist below.
8. Deliver the case study plus the information audit.

The case study structure

Write the six sections in this order. On LinkedIn, headers are optional; in a portfolio page, use them.

1. Problem. What was broken and who felt it. Two to four sentences.
2. Constraints. What bounded the solution: deadlines, budget, hardware, existing systems, skills. One to three sentences. If the only constraint was time, say that honestly; "weekend project" is a real constraint.
3. Decisions. The load-bearing choice, the option it beat, and the reason tied to a constraint. One paragraph, maybe two.
4. Implementation. The one or two mechanisms worth explaining, with a gloss for mixed audiences. Do not narrate every module.
5. Outcome. What happened, with scale and measurement context, and one honest limitation. Partial outcomes are allowed: "used by me and two coursemates; breaks when the university changes the spreadsheet format."
6. Learning. One specific, operational takeaway. If the learning changed later behavior, say so; that is the strongest form.

Truth and credibility rules

• Full triage per credibility-rules.md before drafting.
• Protected categories at high risk here: employers, job titles, team size, user counts, performance metrics, awards, clients. None appear unless the user stated them with context.
• Role inflation is the case-study-specific sin. Watch for it in every sentence with a first-person verb.
• "Production" appears only with production traffic that is KNOWN.
• Team size is stated when the project was a team effort. Solo voice on a team project is a credibility leak readers notice.
• Outcomes that are unmeasured are written as unmeasured. "It worked well in use" is acceptable; "it improved efficiency by 40%" is a measurement and needs a source.

Writing rules

• Default voice per voice-guide.md.
• Length: 250 to 600 words for a portfolio page; 150 to 300 for a LinkedIn-native version. The skill delivers the version requested and can compress on request.
• Write to demonstrate judgment, not to sell the artifact. The reader should see more thinking than adjectives.
• Not every project is a story of transformation. Some case studies are quiet: "the problem was small, the fix was simple, here is what it taught." That is allowed and often more believable.
• Banned: "passionate", "cutting-edge", "seamless", "leveraged", "state-of-the-art", and the false-vulnerability opener ("I almost gave up...") unless it actually happened and actually matters.

Output format

[The case study, in the six-section structure]

[Information audit]
KNOWN: ...
INFERRED: ...
UNKNOWN (not claimed): ...

[Compression note]
One sentence on which section to cut first if the user needs it shorter.

Worked example

Input (summary): a third-year CS student built a course scheduler for their university's elective system; the university publishes courses as a messy spreadsheet; clashes were common; the tool parses the spreadsheet, builds constraints (no clashes, max six courses, labs after lectures), and solves with backtracking; the student used it for their own semester and two coursemates used it; it breaks when the spreadsheet format changes; most time went to parsing and prerequisite modeling.

Output (the case study, compressed for LinkedIn):

Problem: my university publishes electives as a messy spreadsheet.
Picking six courses without clashes meant cross-referencing by hand, and
clashes were common.

Constraints: a weekend-scale project, one developer, and a data source I
don't control. The spreadsheet's format changes without notice.

Decision: I chose a plain backtracking search over a proper solver
library. The search space is small (dozens of courses, hard constraints),
so solver sophistication bought nothing. The real problem was
representing prerequisites, which took most of the time.

Implementation: a parser that tolerates the spreadsheet's quirks, a small
constraint model, and a backtracking search that returns feasible
schedules in under a second.

Outcome: I planned my own semester with it, and two coursemates planned
theirs. It breaks whenever the university changes the spreadsheet layout,
which happened once. Parsing is the weak point, not the solver.

Learning: constraint modeling matters more than the solving algorithm.
I've since applied the same lesson to a validation layer at work: most of
the difficulty is representing the rules, not searching the space.

Note what the draft does: the outcome is real, small, and stated without embarrassment, and the limitation is named. That combination is what makes the rest believable.

Edge cases

• The project was team work and the user cannot separate their contribution. Ask questions until the boundary is visible, or write the case study in "we" and mark the user's part explicitly.
• The project failed or was abandoned. A case study of a failure is legitimate: problem, constraints, decisions, what killed it, learning. Do not force a success arc.
• The user wants marketing copy instead. Decline the inflation, not the request: deliver the honest version and explain that case studies persuade by specifics.
• Client work. Confirm what is publicly attributable; anonymize the client otherwise ("a fintech startup") only if the user confirms the characterization is truthful.
• Old project, faded details. Write only what the user can still attest to. Unknown links in the story chain stay unknown.

When NOT to use this skill

• The goal is a short announcement post: use project-post-writer.
• The material is research: use research-to-linkedin.
• The draft already exists and needs cleanup: use technical-humanizer.
• The user wants resume bullets: different artifact; this skill can draft them from the case study but should say they follow different conventions (terser, still no inflation).

Shared references

• ../../references/technical-storytelling.md — the spine this skill formalizes
• ../../references/credibility-rules.md — the fact triage system
• ../../references/voice-guide.md — voice rules and banned patterns

These paths assume the full repository is present. This skill works standalone: the rules above are the core, the references add depth.