| name | harvest-learnings |
| description | Extract transferable learnings from a client engagement (or strategic prep session) and stage them in `Strategy/to integrate/` for later canonical integration. Reads engagement artifacts from `clients/<client>/`, cross-references against the canonical strategy docs (paths read from `.skill-config.yml`), and drafts a properly-sourced staging doc using the to-integrate TEMPLATE.md. Use when the user says 'harvest learnings from [engagement]', 'what did we learn from [client]', 'feedback loop time', 'lessons from [client]', 'wrap up [engagement]', or 'extract insights from this work'. Does NOT modify canonical docs — that's the sister `integrate` skill's job. Manual invocation only. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
harvest-learnings
Capture transferable patterns from completed (or in-progress) client work and stage them in Strategy/to integrate/ for later canonical integration. Closes the feedback loop from per-engagement work back to the strategy layer.
The skill produces a single staged doc that the user reviews and integrates intentionally via the sister integrate skill — never an automatic canonical update.
Path parameterization: Canonical doc paths are read from .skill-config.yml. If your workspace doesn't use the default names (e.g. Context/positioning-canvas.md), edit the config; this skill follows it.
When to use
- After a substantive client conversation that produced a reframe or new insight
- At the end of a phase, sprint, or engagement
- When the user explicitly asks: "harvest learnings from [X]" / "what did we learn here" / "feedback loop time" / "lessons from [client]" / "wrap up [engagement]"
- After a multi-day strategic prep session that produced new framing
- After a major reframe (positioning shift, role redefinition, new artifact type that worked, frame/metaphor that emerged)
When NOT to use
- For per-engagement task tracking → use the engagement's task system (ClickUp / Notion / etc.)
- To update canonical docs directly → that's the sister
integrate skill (manual review + intentional edits)
- For one-off conversation captures with no transferable signal → just jot a note
- When source artifacts don't exist yet → first ensure the engagement has at minimum an AGENTS.md, an empathy doc, and one captured call
Step 1: Confirm scope (cheap, ~30 seconds)
Two things to confirm before reading:
- Source engagement — which
clients/<client>/ to harvest from. If user said the name, just confirm: "Harvesting from clients/<name>/ — confirm?" If ambiguous, list options from Glob: clients/*/AGENTS.md and ask.
- Time window — entire engagement, or since last harvest? Default: since last
Strategy/to integrate/*-<client>*.md if one exists; otherwise entire engagement.
Don't ask multiple clarifying questions. One focused confirmation, then proceed.
Symlink awareness
clients/<name>/ folders are typically symlinks to real repos elsewhere on disk. Reads via the symlink path are fine. Writes go to Strategy/to integrate/ which is NOT a symlink, so this isn't a concern for output. But cross-reference engagement files using the symlink path (clients/<name>/...) — that's what's stable from the meta-workspace's perspective.
Step 2: Get the current date
Get today's date in the user's local timezone (use the time MCP / date command). Required for:
- Filename:
YYYY-MM-DD-topic-source.md
- Doc's
*Created: YYYY-MM-DD* line
- Update log row
Never hardcode the date.
Step 3: Inventory source artifacts
Read systematically. Expected artifact set for a client engagement:
| Artifact | What it gives you | Status if missing |
|---|
clients/<client>/AGENTS.md | Operating context, conventions, what to avoid | Critical — if missing, stop and tell the user |
clients/<client>/README.md | Engagement framing, partner context, file index | Note absence, continue |
clients/<client>/context/<person>/empathy-objective.md | Buyer-as-person lens; empathy quotes; objectives stated and inferred | Critical for Categories 1, 6 — if missing, flag |
clients/<client>/context/engagement-insights.md | Engagement-level synthesis: insights, leverage, follow-ups | Critical for Categories 2, 3, 5 — if missing, flag |
clients/<client>/context/<person>/<date>-*.md (call captures) | Verbatim quotes with timestamps — gold for Category 6 | Note count; more is better |
clients/<client>/context/email-chains/*.md | Multi-party dynamics; vendor / partner context | Optional |
| Task statuses (if accessible via project task MCP) | What was actually executed; what was deferred | Optional |
If critical artifacts are missing, stop and tell the user what's needed. Don't fake-harvest from thin source material.
Step 4: Extract patterns across the 6 categories
Each becomes a section in the output doc. Some categories may be empty for a given engagement — that's fine; better empty-and-honest than fabricated.
Category 1: Concrete behaviors that landed (or didn't)
What positioning / role / posture moves were made? Which worked? Which didn't? Each behavior should be:
- Observable (a third party could see it happen)
- Sourced (cite the artifact or moment — file path, transcript timestamp)
- Generalizable (could apply to another engagement)
Category 2: Frames, metaphors, language that emerged
Did a new way of describing the work surface? A metaphor introduced by you or the buyer? Internal vs. external vocabulary distinctions?
Category 3: Role-shape signals — what's actually being sold
What did the buyer think they were buying? What did they actually need? What was the role in practice (not as named in any contract)? What disqualifies it?
Category 4: Document/artifact types that worked
What artifacts produced clarity? Which were skipped or replaced? Categorize as:
- Per-client (internal) — empathy doc, engagement-insights doc, captured calls
- Per-conversation (client-facing) — flow chart, decisions list, glossary
- Strategic-layer (cross-engagement) — role one-pager, phase/roadmap doc
Category 5: Problem types being solved
Which patterns of buyer pain recurred or were named? These are the hooks to recognize in future engagements.
Category 6: Empathy statements — buyer's own language
Concrete buyer quotes the practice should be calibrated to recognize. Format as a table: quote → what it means → response pattern. Source-cite every quote. Primary candidates for the swipe-file canonical doc.
Step 5: Cross-reference against existing Strategy/to integrate/ content
Glob: Strategy/to integrate/*.md
For each existing file, read enough to check for overlap. Three possible outcomes per pattern:
- Net new → goes in the new doc
- Extends an existing pattern → either extend the existing doc directly OR add to new doc with a
> See also: [existing-doc] link
- Already captured → skip; mention in the report
Don't duplicate. The to integrate/ folder is a clean staging area, not a churn log.
Step 6: Cross-reference against canonical docs
Read paths from .skill-config.yml. Default canonical doc list (resolved per workspace):
| Logical name | Default path | What's in it |
|---|
positioning_canonical | Context/positioning-canvas.md | Three-part core statement, engagement shape, what attracts/filters |
swipe_file | Context/swipe-file.md | Buyer-language analogs |
working_with | Context/working-with-X.md | Collaborator handoff |
self_profile | Context/self-profile.md | Operating defaults, blind spots |
strat_summary | Strategy/strat-summary.md | Current working strategy |
evidence_ledger | Strategy/evidence-ledger.md | Falsification layer |
Use Grep to check whether a specific pattern's keywords already appear in canonical. If it does and the new evidence corroborates: don't restage; add a note to the output flagging it as a candidate for the Evidence Ledger. If it does and the new evidence contradicts: flag prominently — refutation is high-value signal.
If a pattern is NOT in canonical: it goes in the staged doc.
If a doc in .skill-config.yml is marked not_in_use: true, skip cross-referencing it.
Step 7: Draft the staging doc
Use Strategy/to integrate/TEMPLATE.md as the structural starting point. Required elements:
- Filename:
Strategy/to integrate/YYYY-MM-DD-topic-source.md
- First line:
*Status: To integrate. Source: [engagement name + date range].*
- Created date:
*Created: YYYY-MM-DD*
- TL;DR section at top — 3–5 bullets, each a quotable sentence
- Per-category sections populated from Step 4 (skip empty categories or note "no significant patterns this round" — don't fabricate)
- "What needs validation across other engagements" — honest about N=1 limits; concrete questions to test next
- "Where this should integrate" — a target-by-target mapping naming specific canonical docs (use the table from Step 6)
- Update log with one row stamped today
Source-cite every claim. Use clickable links where possible (transcript timestamps, file paths). A claim without a source isn't a learning — it's a guess.
Voice template: read the resolved voice_profile doc (from .skill-config.yml) before drafting if you need to recalibrate.
Step 8: Report back
Staged: Strategy/to integrate/<filename>
Captured (X patterns across Y categories):
- Category 1 (behaviors): <count> — <one-line summary>
- Category 2 (frames): <count> — <one-line summary>
- Category 3 (role-shape): <count> — <one-line summary>
- Category 4 (artifacts): <count> — <one-line summary>
- Category 5 (problem types): <count> — <one-line summary>
- Category 6 (empathy quotes): <count> — <one-line summary>
Skipped:
- <pattern>: <reason — already in canonical / duplicates existing to-integrate / no source>
Suggested next move:
- validate (wait for second engagement) | partial-integrate (specific pieces ready now) | wait
- If integrate-ready: which canonical docs are the targets
- If wait: what corroboration would unlock integration
Keep it tight. The user reads this to decide what to do next.
What this skill does NOT do
- Does NOT modify any canonical strategy doc — that's
integrate's job
- Does NOT modify the Evidence Ledger directly (only flags candidates in the output doc)
- Does NOT delete or archive anything from
Strategy/to integrate/ (manual after intentional integration)
- Does NOT commit to git
- Does NOT fabricate patterns to fill empty categories
- Does NOT over-stage — if only one or two transferable patterns surfaced, ship a short doc
- Does NOT run automatically — manual invocation only
- Does NOT synthesize across multiple engagements in a single run — one harvest per session
Best practices
- Source-cite everything. Every claim needs a file path, transcript timestamp, or email date.
- Honor N=1. Single-engagement insights LOOK transferable but often aren't. Flag them and list what would validate them.
- Match voice. Read the resolved
voice_profile doc if you need to recalibrate.
- Skip empty categories cleanly. A 4-section doc with substance > a 6-section doc with filler.
- Stage, don't integrate. The skill's job ends at producing the staged doc.
- Filename hygiene:
YYYY-MM-DD-topic-source.md. Keep topic-source short, lowercase, hyphen-separated. The source is usually a client slug.
- One harvest per session. Cross-engagement synthesis is a different (more expensive) move that deserves its own future skill.
Sister skill
integrate handles the next step: take a Strategy/to integrate/ doc, propose specific edits to canonical, get the user's approval per-edit, apply, then archive the source.
If the user asks to integrate from this skill: redirect — "Harvest is staged. Want me to invoke integrate next?" — don't try to do both jobs in one skill.
