portfolio-resume

Portfolio Resume

Session entry point for returning to portfolio work. This skill orients the user by showing where they left off and what to do next — think of it as the dashboard view that keeps multi-session projects on track.

Core Concept

Plugin root resolution. Bash invocations below resolve the plugin root inline as ${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/insight-wave/cogni-portfolio/*/ | head -1)} — the first call works whether or not the harness injects $CLAUDE_PLUGIN_ROOT. Keep the inline form in every call; do not strip it.

Portfolio projects span multiple sessions and skills. Without a clear re-entry point, users lose context between sessions and waste time figuring out what they already did. This skill bridges that gap: it reads the project state, surfaces progress at a glance, and recommends the most valuable next step. The goal is to get the user back into productive flow within seconds.

Workflow

1. Find Portfolio Projects

Discover portfolio projects in the workspace using the discovery script. The script resolves the workspace root automatically (priority: --root > $PROJECT_AGENTS_OPS_ROOT > walk-up from $PWD to find a cogni-portfolio/ ancestor > $PWD) and also returns projects from the global registry (~/.claude/cogni-portfolio-projects.json) so workspaces hosted outside the insight-wave repo (OneDrive, Dropbox, client folders) surface even when cwd is unrelated.

bash "${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/insight-wave/cogni-portfolio/*/ | head -1)}/scripts/discover-projects.sh" --json

Returns JSON with count, search_root, and a projects array. Each project entry includes path (absolute), slug, company_name, company_industry, language, updated, and pipeline-stage flags (has_products, has_features, has_markets, has_propositions, has_solutions, has_dashboard). Pass path verbatim — absolute — to every subsequent script call; never reconstruct it from $PWD.

The script searches:

1. The resolved workspace root for cogni-portfolio/*/portfolio.json
2. The global project registry (~/.claude/cogni-portfolio-projects.json) for projects created in other workspaces

If count is 0:

• First, ask the user if they have a project in a different directory (e.g., OneDrive, external workspace). If they provide a path, register it once and re-run discovery:

  bash "${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/insight-wave/cogni-portfolio/*/ | head -1)}/scripts/discover-projects.sh" --register "<path>"
  

  Surface the detected search_root in your prompt so the user can see where discovery looked: "I checked <search_root> and didn't find a portfolio. Is the project somewhere else?"
• If the user confirms no project exists yet, briefly tell them "No portfolio project exists in this workspace yet — let's set one up" (in their language if known) and dispatch the portfolio-setup skill via the Skill tool to begin initialization. Do not ask the user to re-issue a command; the handoff should be seamless. Once setup completes, control returns here naturally — the user can re-invoke /portfolio-resume to see the new project's status, or simply continue with the next-step recommendations setup printed.

This makes portfolio-resume a safe single entry point: returning users get the dashboard, new users get walked into setup, and nobody has to know which lifecycle stage they're in.

2. Select Project

• One project found — use it automatically.
• Multiple projects — present them and ask which one to continue.

3. Run Project Status with Health Check

bash "${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/insight-wave/cogni-portfolio/*/ | head -1)}/scripts/project-status.sh" "<project-dir>" --health-check

The script returns JSON with counts, phase, next_actions, completion, claims, and stale_entities. The --health-check flag enables staleness detection — it compares upstream updated dates (or file mtimes as fallback) against downstream entities and flags propositions/solutions that may need refresh.

4. Present Status Summary

Show a concise, scannable dashboard. Lead with the company name and project slug, then the progress table:

Entity	Count	Status
Taxonomy	type or "none"	source (bundled / project-local / none) · validation (pass / fail / skipped). If taxonomy.source == "project-local" and taxonomy.validation == "fail", append the error count from taxonomy.validation_errors
Scan	mode or "not run"	scan.categories_confirmed / scan.categories_total confirmed, scan.categories_not_offered not offered (only when scan.has_metadata == true)
Products	N
Features	N
Markets	N
Propositions	N / expected (E excluded)	pct%
Solutions	N / propositions	pct%
Packages	N / packageable	pct%
Competitors	N / propositions	pct%
Customers	N / markets	pct%
Claims	N total	V verified, D deviated, U unverified, P pending propagation. If claims.pending_stale > 0, append: "(S on stale entities — deferred)"
Communicate	N files	A accepted, R revise, J rejected (if > 0), STALE if upstream changed
Architecture	exists/missing	STALE if products/features changed since last generation
Purpose	N / total features	coverage percentage — low coverage limits architecture and customer narrative quality
Context	N entries	breakdown by category (e.g., 3 pricing, 2 competitive, 1 strategic)
Sources	N (D docs, U urls)	S stale, C current (only if source_lineage.has_registry is true)
Uploads	N	pending ingestion (if > 0)

The Propositions row uses counts.expected_propositions as the denominator — this value already subtracts excluded pairs. Do NOT compute your own expected count by multiplying features × markets. Show as N / expected (E excluded) where E is counts.excluded_pairs. Only show the "(E excluded)" suffix when E > 0. When N equals expected, show 100% — excluded pairs are design decisions, not gaps.

If margin_health is present in the status output and has solutions_with_cost_model > 0, add a margin health line after the table:

• Margin health — N solutions with cost models, N tiers below target (target: Y%), N negative-margin tiers. Show margins split by type: project avg margin X%, subscription avg gross margin X%. These are different metrics (effort-based vs. unit economics) so present them separately. Flag negative project margins and subscription LTV/CAC < 3 as urgent.

If solutions_by_type is present, show the type breakdown: "N project, N subscription, N partnership".

If blueprint_status is present and has version_drifted > 0, add a blueprint drift line:

• Blueprint drift — N solutions were generated from an older blueprint version and may need regeneration. List the drifted solution slugs (from drifted_solutions). Recommend: "Run the solutions skill in review mode to check drift and selectively regenerate." Also show blueprint coverage: "N products have delivery blueprints, N solutions were generated from blueprints."

After the table:

• Phase — translate the phase value into plain language (see reference below)
• Quality audit — if quality_audit is present and has flagged entities (features_flagged or propositions_flagged non-empty), show them grouped by issue type before stale entities. Present actionable summaries, not raw data:
  • Group by dimension: "2 features have descriptions outside 20-35 word target (cloud-monitoring: 48 words, api-gateway: 12 words)"
  • For parity language: "1 feature uses parity language ("innovative", "robust")"
  • For proposition issues: "1 proposition DOES is too long (42 words, target 15-30)"
  • If a flagged feature has downstream propositions, note the cascade risk: fixing the feature description may require refreshing its propositions
  • Deferred vs new warnings: If the quality assessment data includes deferred features (features where the user chose to skip a warning), present them separately: "Deferred from previous session: cogni-sales (12 words — you chose to skip this)". New warnings (features created or edited since the last quality check) are presented normally. This distinction prevents surprise — the user should recognize deferred items as conscious decisions, not new problems.
  • End with actionable guidance: "Consider running features or propositions skill to review and fix these before generating downstream content."
  • Offer deep assessment: "For thorough quality assessment including mechanism and customer-relevance checks, ask for a full quality audit."
  • If no entities are flagged, skip this section entirely (don't show "0 flagged")
• Source drift — if source_lineage.has_registry is true and drift is detected, show this section BEFORE stale entities (since source drift is often the root cause of entity staleness):
  • If source_lineage.changed_uploads is non-empty: "N source documents have been re-uploaded with changes (list filenames). These affect M entities." Group affected entities by source. Recommend: "Run portfolio-lineage to assess impact, or portfolio-ingest to re-process the updated documents."
  • If source_lineage.new_uploads is non-empty: "N new files in uploads/ have not been ingested yet." Distinguish from changed re-uploads.
  • If source_lineage.stale_sources > 0 and no changed_uploads: "N source entries are marked as stale in the registry." Recommend running portfolio-lineage check to investigate.
  • If source_lineage.untracked_entities > 0: "N entities have no source lineage tracking." This is informational, not urgent — mention it after other drift warnings. Recommend running portfolio-lineage to backfill.
• Stale entities — if stale_entities is non-empty, show them as priority actions before the regular next steps. Group by reason type: "N propositions need refresh because their upstream features were updated" is more useful than listing each one. If a stale entity also has quality warnings, lead with the quality issue (fix the root cause first, then refresh the proposition). When stale entities AND unverified claims coexist, note the interaction: if claims.pending_stale > 0, explain that those claims sit on entities about to be refreshed — verifying them now would be wasted work since the refresh will generate new claims. This helps the user understand why verify isn't the first recommended step despite having hundreds of pending claims.
• Stale communicate files — if communicate.stale is true, highlight this prominently: "Communicate files may need refresh — upstream data changed since they were generated." Present the reason from communicate.stale_reason. Recommend running portfolio-communicate to regenerate. This appears alongside stale entity warnings since it represents the same class of problem (downstream output invalidated by upstream changes).
• Stale architecture diagram — if architecture.stale is true, mention that the architecture diagram may be outdated because products or features changed since it was generated. Recommend running portfolio-architecture to refresh. If architecture.exists is false and features exist, suggest generating the architecture diagram as a visual checkpoint.
• Purpose coverage — if purpose_coverage.total_features > 0 and purpose_coverage.with_purpose is less than half of total_features, note low purpose coverage: "N of M features have purpose statements. Adding purpose improves architecture diagrams and customer-facing materials." Recommend running the features skill to add purpose statements.
• Context notice — if counts.context_entries > 0, mention available context entries with a category breakdown. Read context/context-index.json for the by_category map to show counts per category. This helps the user understand what intelligence is available for downstream skills. If context exists but downstream skills haven't been run yet, highlight this: "N context entries from ingested documents are ready — these will automatically inform propositions, solutions, and other skills."
• Taxonomy state — this is the first status signal to surface after the table, because scan and downstream classification all depend on it. Read the taxonomy block from the script output:
  • If taxonomy.configured == false: call it out as a blocking action — "No taxonomy configured yet. Run portfolio-taxonomy to clone a bundled template, author one, or import an external taxonomy before running portfolio-scan." Suppress any portfolio-scan recommendation from next_actions until the taxonomy is in place (the script already does this, but reinforce it in the narrative).
  • If taxonomy.source == "project-local" and taxonomy.validation == "fail": show the failed-check names from taxonomy.validation_errors inline ("categories_json: invalid JSON; category_id_format: cannot validate"). Route the user to portfolio-taxonomy to fix or hand-edit, then re-run status with --health-check to re-validate. Scan is blocked until this clears.
  • If taxonomy.source == "project-local" and taxonomy.validation == "pass": one line acknowledging the project-local taxonomy ("Using customized taxonomy ({type}, cloned from {cloned_from}) — edits survive plugin updates"). Informational, no action.
  • If scan.has_metadata == true and scan.categories_not_offered > scan.categories_total / 3: informational — "Scan covered {categories_confirmed}/{categories_total} categories; {categories_not_offered} were empty. If that feels over-scoped for this company, portfolio-taxonomy can trim." Never auto-recommend — this is a judgment call that depends on domain context.
• Uploads notice — if counts.uploads > 0, always mention pending files regardless of phase. When source_lineage.has_registry is true, distinguish between new uploads (source_lineage.new_uploads) and re-uploads (source_lineage.changed_uploads): "N new uploads (never ingested) + M re-uploads (source changed since last ingestion)"
• Gaps — handle exclusions and missing pairs in this order:
  1. Check excluded_pairs from the script output FIRST. These are confirmed design decisions recorded in feature files with explicit reasons — not guesses. If non-empty, state definitively: "N Feature × Market Paare bewusst ausgeschlossen (Design-Entscheidung)." Never use speculative language like "vermutlich" or "möglicherweise" for excluded pairs.
  2. Check missing_propositions — this array already excludes excluded pairs, so any entries here are genuine gaps. List them as actionable items.
  3. If missing_propositions is empty, the proposition matrix is complete. Do NOT list excluded pairs as missing or suggest creating them. A brief mention of the exclusion count in the table row is sufficient.
  4. If the script reports counts.excluded_pairs: 0 but missing_propositions contains pairs, cross-check by reading feature files for excluded_markets arrays as a fallback — the script may have failed to detect them.
  5. Note incomplete solutions/competitors/customers as separate items.

Keep the tone warm and oriented toward action — this is a welcome-back moment, not a status report. The user should feel oriented, not overwhelmed.

5. Recommend Next Action

Present entries from next_actions sorted by priority (ascending). Lower priority numbers represent upstream work that must complete before higher-numbered downstream actions can produce quality output.

Presentation rules:

• Lead with the lowest-priority (most upstream) action as the primary recommendation
• If multiple actions share the same priority, present them as parallel options the user can tackle in any order
• When a higher-priority action (e.g., communicate at 10) appears alongside a lower-priority action (e.g., packages at 8), explicitly note the dependency: explain why the upstream action should come first
• Offer to proceed with the top (lowest priority number) recommendation immediately

Common dependency pairs — explain these when both appear:

• portfolio-taxonomy (2) before portfolio-scan (2) — scan reads the taxonomy to classify findings, so a missing or broken taxonomy yields a broken scan report. When taxonomy.configured == false or taxonomy.validation == "fail", the script does not emit a scan action; explain the block explicitly so the user knows why.
• portfolio-scan (2) as an alternative to products (2) when products are empty and a valid taxonomy is in place — scan auto-populates products and features from the web; present both at the same priority as parallel options, not as a queue.
• packages (8) before communicate (10) — communicate generates deliverables from package data; without current packages, output will be incomplete
• solutions (7) before packages (8) — packages bundle solutions into tiers; missing solutions mean incomplete bundles
• propositions (6) before solutions (7) — solutions implement proposition DOES/MEANS; no propositions means nothing to implement
• features (3) before propositions (6) — propositions map features to markets; feature changes invalidate downstream propositions
• propositions (6) before verify (9) when propositions are stale — refreshing generates new claims, making verification of old claims on those entities wasted work. The claims.pending_stale count tells you how many claims fall into this category.
• ingest (1) before everything — new document data may change features, markets, or other entities

If the phase is complete, congratulate the user and suggest reviewing outputs or running portfolio-communicate for additional deliverables. If communicate files are stale (indicated by a communicate action in next_actions), mention that portfolio-communicate should be re-run to refresh customer-facing documentation.

After presenting the recommendation, optionally add a one-line pointer to portfolio-setup as a side-door for starting a new portfolio project (different company or product line). Only surface this when the current project is in a steady state — phase is complete, no stale entities, no quality warnings, no source drift, no pending uploads — so it does not compete with priority-ordered workflow actions. Frame it briefly, e.g. "If you want to start a portfolio for a different company or product line, run portfolio-setup." This is an orientation aid, not a recommendation; portfolio-setup itself redirects back to portfolio-resume when a project for the same company already exists, so there is no risk of accidental duplication.

Phase Reference

Phases below are the states the script reports via the top-level phase field plus three cross-cutting taxonomy/scan states that surface via next_actions entries rather than phase itself. In other words: products can be the phase value while the user sees a portfolio-taxonomy or portfolio-scan action as the first recommendation, because those actions are emitted from the phase-independent block and sorted ahead of the phase-specific one by priority.

Phase	Meaning	What to do
taxonomy (cross-cutting — emitted whenever taxonomy.configured == false)	No taxonomy configured on the project	Run portfolio-taxonomy to clone a bundled template, author from scratch, or import an external one. Scan is blocked until this is in place.
taxonomy-invalid (cross-cutting — emitted whenever taxonomy.source == "project-local" and taxonomy.validation == "fail")	Project-local taxonomy fails validation	Run portfolio-taxonomy to fix, or hand-edit the taxonomy files under {PROJECT_PATH}/taxonomy/ and re-run status with --health-check to re-validate. Scan is blocked until validation passes.
scan (cross-cutting — emitted when products are empty, a valid taxonomy is configured, and scan.has_report == false)	Taxonomy ready, no scan output, products empty	Run portfolio-scan to auto-discover offerings from the web. Presented at the same priority as products so the user can also define products manually — this is a choice, not a queue.
products	No products defined yet	Run products skill
features	Products exist, no features	Run features skill
markets	Features defined, no markets	Run markets skill
customers	Markets defined, no customer profiles yet	Run customers skill (or skip to propositions for weaker messaging)
propositions	Feature x Market pairs need messaging	Run propositions skill
enrichment	Propositions exist, solution/competitor gaps remain	Run solutions, compete, and/or customers for remaining markets
verification	Unverified or deviated claims pending	Run verify skill
propagation	Resolved claims with corrections not yet applied to entity files	Run verify skill (Step 8 propagates corrections)
communicate	All entities complete, claims clean, corrections propagated	Run communicate skill
complete	All workflow stages finished	Review outputs or refresh communicate if upstream data changed

Multi-Session Design

This skill is the recommended re-entry point after heavy sessions. Portfolio work naturally spans multiple sessions — batch proposition generation, competitive analysis, solution design, and dashboard generation each consume significant context. Other portfolio skills proactively recommend /portfolio-resume when they detect a heavy session (multiple batch operations, 3+ skills invoked, or capstone operations like portfolio-dashboard/portfolio-communicate completed).

When presenting the status summary, acknowledge what the user accomplished in previous sessions if recent entity timestamps suggest a productive recent session. This continuity helps users feel their work persists and builds confidence in the multi-session workflow.

Language

• Communication Language: Read portfolio.json in the project root. If a language field is present, communicate with the user in that language (status messages, instructions, recommendations, questions). Technical terms, skill names, and CLI commands remain in English. If no language field is present, default to English.