skillpacks 0.1.1 → 0.1.2

package/packs/session-analytics/claude/analyze-sessions/archive/v0.2/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: analyze-sessions
+description: Analyze Claude Code and Codex session history for cross-session trends, recurring patterns, and automation opportunities
+type: analysis
+version: v0.2
+argument-hint: "[history file, session directory, repo path, date range, or trend question]"
+interview_depth: none
+visual_tier: visual
+---
+
+# Analyze Sessions
+
+Use this skill when the user wants a data-driven breakdown of local Claude Code and Codex usage history across conversations, sessions, tools, projects, or time periods. This skill is for broad trend analysis, repeated prompt patterns, recurring frustrations, workflow evolution, automation opportunities, and skill performance over multiple sessions.
+
+If the user asks about one current session, one mistake, one correction, one repo incident, or one skill failure, route to `/session-triage` instead of handling the incident here.
+
+## Inputs
+
+- Default Claude history file: `~/.claude/history.jsonl`
+- Default Codex prompt history file: `~/.codex/history.jsonl`
+- Default Codex rich session root: `~/.codex/sessions/**/*.jsonl`
+- Optional paths from the user. Accept history files, session directories, repository directories, or exported logs.
+- Optional filters such as repo path, project name, date range, command/skill name, exact phrase, or trend question.
+- Optional model pricing table or explicit request to verify current provider pricing. Use pricing only when it is supplied by the user, present in the logs, or verified from an authoritative provider source during the run.
+
+## Process
+
+1. Confirm the request is broad enough for cross-session analysis:
+   - Continue when the user asks for overall history, usage breakdowns, repeated prompts, recurring workflow issues, cross-tool changes, automation opportunities, or performance trends across multiple sessions.
+   - Route to `/session-triage` when the user asks to investigate one immediate issue, correction, failed run, session, repo incident, or skill mistake.
+   - When a request contains both a single incident and recurrence questions, recommend `/session-triage` first for the incident and use this skill afterward for frequency or trend evidence.
+
+2. Read the full available history for the selected scope, not a sample.
+
+3. Use a scriptable approach for scale. Prefer streaming or line-by-line processing for large files.
+
+4. Normalize records into one common shape:
+   - `source`: `claude` or `codex`
+   - `timestamp`
+   - `session_id`
+   - `project` or `cwd`
+   - `text`
+   - optional token usage such as input, cached input, output, reasoning output, and total tokens
+   - optional cost metadata such as estimated USD cost, billed credits, pricing source, and price-table version
+   - optional metadata such as git branch, repository URL, model, provider, and CLI version
+
+5. Parse Claude history:
+   - `~/.claude/history.jsonl` lines contain user messages with fields such as `display`, `timestamp` in milliseconds, `project`, `sessionId`, and `pastedContents`.
+
+6. Parse Codex history:
+   - `~/.codex/history.jsonl` lines contain compact user prompts with `text`, `ts` in seconds, and `session_id`.
+   - `~/.codex/sessions/**/*.jsonl` lines contain richer rollout records. Use `session_meta.payload.id` to map session IDs to `cwd`, git metadata, CLI version, and model/provider.
+   - Include user `response_item` records only when they represent user messages. Exclude developer/system/base instruction payloads from prompt-pattern counts.
+   - Prefer compact Codex prompt history for user prompt counts, enriched with rollout metadata. Use rollout user records only for prompts missing from compact history or for metadata checks.
+   - Parse Codex `event_msg` records with `payload.type == "token_count"`. Normalize `payload.info.total_token_usage` and `payload.info.last_token_usage` fields such as `input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`, and `total_tokens`.
+
+7. Parse token spend and cost metadata:
+   - For session-level token totals, use the final or highest cumulative `total_token_usage` snapshot per session instead of summing every cumulative snapshot.
+   - For date or turn-level trends, sum deduplicated `last_token_usage` records and reconcile them against each session's final cumulative total when possible.
+   - Attribute token usage by source, session, project, model, provider, and date when those fields are available; otherwise report the missing dimensions explicitly.
+   - Use direct cost fields when logs include them, such as `cost`, `total_cost`, `totalCost`, `estimated_cost_usd`, or `estimatedCostUsd`, preserving their original source and units.
+   - When costs are not logged, estimate USD cost only from a user-provided or freshly verified provider pricing table. Show the pricing source, retrieval date or table version, model mapping, formula, and assumptions.
+   - Treat cached-input and reasoning-output tokens according to the pricing table. If the table is ambiguous, state the assumption, such as reasoning tokens billed as output tokens, and keep the estimate labeled as an estimate.
+   - If no reliable cost basis is available, still report token totals and say cost is unavailable instead of guessing.
+
+8. Extract and report:
+   - Project breakdown: top projects by message volume with percentages.
+   - Source breakdown: Claude vs. Codex message/session counts and date ranges.
+   - Token spend breakdown: total tokens plus input, cached input, output, and reasoning output by source, project, model, and date where supported.
+   - Cost breakdown: total estimated cost, cost by source/project/model/date, and top cost-driving sessions when supported by explicit cost fields or a verified/provided price table.
+   - Activity categories and recurring workflow themes.
+   - Exact and fuzzy repeated prompt patterns.
+   - Common multi-step workflow sequences.
+   - Cross-tool differences, including workflows that moved from Claude to Codex or still require different commands.
+   - Skill performance patterns across multiple invocations, including recurring corrections or repeated bad recommendations when supported by scoped history evidence.
+
+9. For each major pattern, recommend the best automation shape:
+   - Skill: repeatable workflow with a stable sequence.
+   - Agent: complex exploratory or autonomous work.
+   - Plugin/integration: external-service or persistent-connection workflow.
+   - Standing instruction/project convention: behavior that should always apply.
+   - `/session-triage`: one concrete incident needs verification before a durable fix is designed.
+
+## Remediation-Ready Handoffs
+
+When a broad verified workflow gap routes to `/targeted-skill-builder` (skill-dev pack):
+
+- Emit one final next route using the current runner command convention only: `/targeted-skill-builder` (skill-dev pack) `<concrete gap phrase>`.
+- The command argument must name the workflow gap and likely owner surface, not just `analyze-sessions` or `targeted-skill-builder`; for example: `/targeted-skill-builder` (skill-dev pack) `run post-doc-edit validation and lessons capture gate`.
+- In the recommendation table or next-work sentence, name the likely owner surface and one validation expectation, such as a layer1 contract test, focused benchmark smoke, or skill-specific validation command. If ownership is uncertain, state which evidence would decide it instead of guessing.
+- Do not put both Claude slash and Codex dollar commands in the final handoff. It is fine to mention the counterpart route in cross-tool analysis, but the final `Recommended next command:` must be one Claude-native command.
+- Distinguish explicit evidence from inference when labeling source, runner, project, or owner. Use language such as "explicitly says", "implies", or "not stated" rather than assigning runner ownership to sparse logs.
+
+## Output
+
+Produce a structured report with:
+
+- Overview stats: total messages, sessions, date range, and top projects.
+- Source comparison: Claude vs. Codex totals, top projects, command usage, and recent trend.
+- Token and cost check: total tokens, token class breakdown, total estimated cost or explicit `cost unavailable`, pricing source/assumptions, and coverage gaps for sources without usage metadata.
+- Categorized patterns with counts and real examples from history.
+- Skill performance trends when requested or visible in the scoped data.
+- Ranked recommendations table: pattern, frequency, recommendation type, suggested name/description.
+- Highest-impact section: top 5 automations by avoided manual prompts.
+- Recommended next skill: `/session-triage` for any concrete incident that needs verification, `/targeted-skill-builder` (skill-dev pack) `<concrete gap phrase>` for a broad verified workflow gap, or `none` when no follow-up is justified. When recommending `/targeted-skill-builder` (skill-dev pack), include the likely owner surface and validation expectation in the report.
+
+## Constraints
+
+- Process the entire available history for broad usage analysis, not just a sample.
+- Use actual message examples from the history, not hypothetical ones.
+- Be specific about frequencies; show exact counts where possible.
+- Show exact token counts where available and clearly distinguish logged costs from estimated costs.
+- Do not infer token counts from message length when usage metadata is missing.
+- Do not estimate dollar cost from remembered or stale model pricing. Use explicit log cost fields, a user-provided price table, or a current provider source verified during the run; otherwise report cost as unavailable.
+- Avoid double-counting cumulative token snapshots. For Codex `token_count` events, aggregate final session totals from `total_token_usage` and use `last_token_usage` only for deduplicated timeline or turn-level analysis.
+- Group near-identical prompts together.
+- Deduplicate Codex prompts that appear in both `~/.codex/history.jsonl` and rollout files by `(session_id, timestamp, normalized text)` where possible.
+- Do not include system, developer, base instruction, or tool output text in repeated-prompt counts.
+- Do not diagnose one immediate issue here; route it to `/session-triage`.
+- Do not create or modify GitHub Actions workflows.
+- If one source is missing or unreadable, report that clearly and continue with the other source instead of guessing.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/analyze-sessions-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/session-analytics/claude/analyze-sessions/archive/v0.3/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: analyze-sessions
+description: Analyze Claude Code and Codex session history for cross-session trends, recurring patterns, and automation opportunities
+type: analysis
+version: v0.3
+argument-hint: "[history file, session directory, repo path, date range, or trend question]"
+interview_depth: none
+visual_tier: visual
+---
+
+# Analyze Sessions
+
+Use this skill when the user wants a data-driven breakdown of local Claude Code and Codex usage history across conversations, sessions, tools, projects, or time periods. This skill is for broad trend analysis, repeated prompt patterns, recurring frustrations, workflow evolution, automation opportunities, and skill performance over multiple sessions.
+
+If the user asks about one current session, one mistake, one correction, one repo incident, or one skill failure, route to `/session-triage` instead of handling the incident here.
+
+## Inputs
+
+- Default Claude history file: `~/.claude/history.jsonl`
+- Default Codex prompt history file: `~/.codex/history.jsonl`
+- Default Codex rich session root: `~/.codex/sessions/**/*.jsonl`
+- Optional paths from the user. Accept history files, session directories, repository directories, or exported logs.
+- Optional filters such as repo path, project name, date range, command/skill name, exact phrase, or trend question.
+- Optional model pricing table or explicit request to verify current provider pricing. Use pricing only when it is supplied by the user, present in the logs, or verified from an authoritative provider source during the run.
+
+## Process
+
+1. Confirm the request is broad enough for cross-session analysis:
+   - Continue when the user asks for overall history, usage breakdowns, repeated prompts, recurring workflow issues, cross-tool changes, automation opportunities, or performance trends across multiple sessions.
+   - Route to `/session-triage` when the user asks to investigate one immediate issue, correction, failed run, session, repo incident, or skill mistake.
+   - When a request contains both a single incident and recurrence questions, recommend `/session-triage` first for the incident and use this skill afterward for frequency or trend evidence.
+
+2. Read the full available history for the selected scope, not a sample.
+
+3. Use a scriptable approach for scale. Prefer streaming or line-by-line processing for large files.
+
+4. Normalize records into one common shape:
+   - `source`: `claude` or `codex`
+   - `timestamp`
+   - `session_id`
+   - `project` or `cwd`
+   - `text`
+   - optional token usage such as input, cached input, output, reasoning output, and total tokens
+   - optional cost metadata such as estimated USD cost, billed credits, pricing source, and price-table version
+   - optional metadata such as git branch, repository URL, model, provider, and CLI version
+
+5. Parse Claude history:
+   - `~/.claude/history.jsonl` lines contain user messages with fields such as `display`, `timestamp` in milliseconds, `project`, `sessionId`, and `pastedContents`.
+
+6. Parse Codex history:
+   - `~/.codex/history.jsonl` lines contain compact user prompts with `text`, `ts` in seconds, and `session_id`.
+   - `~/.codex/sessions/**/*.jsonl` lines contain richer rollout records. Use `session_meta.payload.id` to map session IDs to `cwd`, git metadata, CLI version, and model/provider.
+   - Include user `response_item` records only when they represent user messages. Exclude developer/system/base instruction payloads from prompt-pattern counts.
+   - Prefer compact Codex prompt history for user prompt counts, enriched with rollout metadata. Use rollout user records only for prompts missing from compact history or for metadata checks.
+   - Parse Codex `event_msg` records with `payload.type == "token_count"`. Normalize `payload.info.total_token_usage` and `payload.info.last_token_usage` fields such as `input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`, and `total_tokens`.
+
+7. Parse token spend and cost metadata:
+   - For session-level token totals, use the final or highest cumulative `total_token_usage` snapshot per session instead of summing every cumulative snapshot.
+   - For date or turn-level trends, sum deduplicated `last_token_usage` records and reconcile them against each session's final cumulative total when possible.
+   - Attribute token usage by source, session, project, model, provider, and date when those fields are available; otherwise report the missing dimensions explicitly.
+   - Use direct cost fields when logs include them, such as `cost`, `total_cost`, `totalCost`, `estimated_cost_usd`, or `estimatedCostUsd`, preserving their original source and units.
+   - When costs are not logged, estimate USD cost only from a user-provided or freshly verified provider pricing table. Show the pricing source, retrieval date or table version, model mapping, formula, and assumptions.
+   - Treat cached-input and reasoning-output tokens according to the pricing table. If the table is ambiguous, state the assumption, such as reasoning tokens billed as output tokens, and keep the estimate labeled as an estimate.
+   - If no reliable cost basis is available, still report token totals and say cost is unavailable instead of guessing.
+
+8. Extract and report:
+   - Project breakdown: top projects by message volume with percentages.
+   - Source breakdown: Claude vs. Codex message/session counts and date ranges.
+   - Token spend breakdown: total tokens plus input, cached input, output, and reasoning output by source, project, model, and date where supported.
+   - Cost breakdown: total estimated cost, cost by source/project/model/date, and top cost-driving sessions when supported by explicit cost fields or a verified/provided price table.
+   - Activity categories and recurring workflow themes.
+   - Exact and fuzzy repeated prompt patterns.
+   - Common multi-step workflow sequences.
+   - Cross-tool differences, including workflows that moved from Claude to Codex or still require different commands.
+   - Skill performance patterns across multiple invocations, including recurring corrections or repeated bad recommendations when supported by scoped history evidence.
+
+9. For each major pattern, recommend the best automation shape:
+   - Skill: repeatable workflow with a stable sequence.
+   - Agent: complex exploratory or autonomous work.
+   - Plugin/integration: external-service or persistent-connection workflow.
+   - Standing instruction/project convention: behavior that should always apply.
+   - `/session-triage`: one concrete incident needs verification before a durable fix is designed.
+
+## Remediation-Ready Handoffs
+
+When a broad verified workflow gap routes to `/targeted-skill-builder` (skill-dev pack):
+
+- Emit one final next route using the current runner command convention only: `/targeted-skill-builder` (skill-dev pack) `<concrete gap phrase>`.
+- The command argument must name the workflow gap and likely owner surface, not just `analyze-sessions` or `targeted-skill-builder`; for example: `/targeted-skill-builder` (skill-dev pack) `run post-doc-edit validation and lessons capture gate`.
+- In the recommendation table or next-work sentence, name the likely owner surface and one validation expectation, such as a layer1 contract test, focused benchmark smoke, or skill-specific validation command. If ownership is uncertain, state which evidence would decide it instead of guessing.
+- Do not put both Claude slash and Codex dollar commands in the final handoff. It is fine to mention the counterpart route in cross-tool analysis, but the final `Recommended next command:` must be one Claude-native command.
+- Distinguish explicit evidence from inference when labeling source, runner, project, or owner. Use language such as "explicitly says", "implies", or "not stated" rather than assigning runner ownership to sparse logs.
+
+## Output
+
+Produce a structured report with:
+
+- Overview stats: total messages, sessions, date range, and top projects.
+- Source comparison: Claude vs. Codex totals, top projects, command usage, and recent trend.
+- Token and cost check: total tokens, token class breakdown, total estimated cost or explicit `cost unavailable`, pricing source/assumptions, and coverage gaps for sources without usage metadata.
+- Categorized patterns with counts and real examples from history.
+- Skill performance trends when requested or visible in the scoped data.
+- Ranked recommendations table: pattern, frequency, recommendation type, suggested name/description.
+- Highest-impact section: top 5 automations by avoided manual prompts.
+- Recommended next skill: `/session-triage` for any concrete incident that needs verification, `/targeted-skill-builder` (skill-dev pack) `<concrete gap phrase>` for a broad verified workflow gap, or `none` when no follow-up is justified. When recommending `/targeted-skill-builder` (skill-dev pack), include the likely owner surface and validation expectation in the report.
+
+## Constraints
+
+- Process the entire available history for broad usage analysis, not just a sample.
+- Use actual message examples from the history, not hypothetical ones.
+- Be specific about frequencies; show exact counts where possible.
+- Show exact token counts where available and clearly distinguish logged costs from estimated costs.
+- Do not infer token counts from message length when usage metadata is missing.
+- Do not estimate dollar cost from remembered or stale model pricing. Use explicit log cost fields, a user-provided price table, or a current provider source verified during the run; otherwise report cost as unavailable.
+- Avoid double-counting cumulative token snapshots. For Codex `token_count` events, aggregate final session totals from `total_token_usage` and use `last_token_usage` only for deduplicated timeline or turn-level analysis.
+- Group near-identical prompts together.
+- Deduplicate Codex prompts that appear in both `~/.codex/history.jsonl` and rollout files by `(session_id, timestamp, normalized text)` where possible.
+- Do not include system, developer, base instruction, or tool output text in repeated-prompt counts.
+- Do not diagnose one immediate issue here; route it to `/session-triage`.
+- Do not create or modify GitHub Actions workflows.
+- If one source is missing or unreadable, report that clearly and continue with the other source instead of guessing.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `npx skillpacks install <pack-name>` to the recommendation.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/analyze-sessions-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/session-analytics/claude/prompt-history-backfill/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — prompt-history-backfill
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/prompt-history-backfill-{topic}.html`. Use a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
+Alignment pages are optional for this operational skill. By default, report the outcome inline and write only the skill's normal durable artifacts (`tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Build `alignment/prompt-history-backfill-{topic}.html` only when the user explicitly requests an alignment page or when the agent explicitly identifies a concrete clarification/review need that cannot be resolved cleanly in conversation or the normal artifacts. When an alignment page is created, use the full contract below and a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
 
 **Visual rendering tier.** Each alignment page declares a rendering tier:
 - `document` (default) — text, tables, approval gates. No charts or interactive elements.
@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-prompt-history-backfill-research.md`; product-path mode uses `research/{slug}/_working/preliminary-prompt-history-backfill-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-prompt-history-backfill-research.md`; product-path mode uses `research/{slug}/_working/preliminary-prompt-history-backfill-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Glossary Additions gate.** When this research introduces domain-specific terms, acronyms, or concept definitions that a reader outside the project would not know, include a `## Glossary Additions` section in the alignment page. Render a table of proposed terms with columns: Term, Definition, Source (`prompt-history-backfill`), Category (business/tooling/workflow/technical/domain), and per-term Approve/Edit/Reject/Flag radio controls. Only user-approved terms are appended to the target glossary (`research/glossary.md` or `research/{slug}/glossary.md` for scoped paths) during the confirmed-page write step. When the skill operates in a product-path scope, ask whether each term belongs in the parent or scoped glossary; default to the scoped glossary.
 

package/packs/session-analytics/claude/prompt-history-backfill/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 2026-06-12
+
+- Made alignment pages optional by default: report inline and write the skill's normal durable artifacts unless the user requests an alignment page or the agent identifies a concrete clarification/review need.
+
 ## v0.1 - 2026-06-04
 
 - Add legacy skill routing: hardcoded map of renamed/removed/never-existed skill slugs (`run`, `review`, `skill-creator`, `verify`, `simplify`, `schedule`).

package/packs/session-analytics/claude/prompt-history-backfill/SKILL.md

@@ -2,7 +2,7 @@
 name: prompt-history-backfill
 description: Scan Claude and Codex conversation history for skill invocation prompts missing from repo prompt history and report or backfill them safely
 type: analysis
-version: v0.1
+version: v0.2
 argument-hint: "[--repo <path>] [--skill <slug>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [history/export paths...]"
 ---
 
@@ -31,7 +31,7 @@ Use this skill when the user wants to audit or backfill `prompts/<skill-slug>/`
    - In report-only mode, prompt backfill candidates are reviewed but no files under `prompts/<skill-slug>/` are created.
 
 2. Resolve known skills in the target repo:
-   - Read active non-archive `SKILL.md` files under `global/`, `packs/`, `.claude/skills/`, and `.codex/skills/` when present.
+   - Read active non-archive `SKILL.md` files under `base/`, `packs/`, `.claude/skills/`, and `.codex/skills/` when present.
    - Include existing `prompts/<skill-slug>/` directories as known prompt-history targets.
    - Maintain a hardcoded legacy skill map for slugs that no longer exist as active skills:
      - `run` — renamed → `exec`
@@ -103,7 +103,7 @@ The report should include:
 
 ## Alignment Page
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/prompt-history-backfill-{topic}.html`.
+By default, this skill reports results inline and writes only its normal durable artifacts (for example `tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Do not build an alignment page automatically. Create `alignment/prompt-history-backfill-{topic}.html` only when the user explicitly requests an alignment page or when you explicitly identify a concrete clarification/review need that cannot be handled cleanly inline; when you create one, follow `ALIGNMENT-PAGE.md` in this skill's directory.
 
 ## Default Shipping Contract
 

package/packs/session-analytics/claude/prompt-history-backfill/archive/v0.1/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: prompt-history-backfill
+description: Scan Claude and Codex conversation history for skill invocation prompts missing from repo prompt history and report or backfill them safely
+type: analysis
+version: v0.1
+argument-hint: "[--repo <path>] [--skill <slug>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [history/export paths...]"
+---
+
+# Prompt History Backfill
+
+Invoke as `/prompt-history-backfill`.
+
+Use this skill when the user wants to audit or backfill `prompts/<skill-slug>/` prompt-history artifacts from local Claude Code and Codex conversation history. The skill identifies visible user prompts that invoked skills, compares them with the target repository's prompt-history convention, and produces a reviewable report by default.
+
+## Inputs
+
+- Default target repository: current working directory.
+- Optional `--repo <path>` to target another repository.
+- Optional `--skill <slug>` to limit detection and output to one skill.
+- Optional `--since YYYY-MM-DD` and `--until YYYY-MM-DD` filters.
+- Optional user-provided history files, exported logs, or session directories.
+- Default Claude history file: `~/.claude/history.jsonl`.
+- Default Codex prompt history file: `~/.codex/history.jsonl`.
+- Default Codex rich session root: `~/.codex/sessions/**/*.jsonl`.
+
+## Process
+
+1. Resolve arguments and mode:
+   - Default mode is report-only.
+   - Do not create, modify, or remove prompt files unless the visible invocation includes explicit `--apply`.
+   - In report-only mode, prompt backfill candidates are reviewed but no files under `prompts/<skill-slug>/` are created.
+
+2. Resolve known skills in the target repo:
+   - Read active non-archive `SKILL.md` files under `global/`, `packs/`, `.claude/skills/`, and `.codex/skills/` when present.
+   - Include existing `prompts/<skill-slug>/` directories as known prompt-history targets.
+   - Maintain a hardcoded legacy skill map for slugs that no longer exist as active skills:
+     - `run` — renamed → `exec`
+     - `review` — renamed → `expert-review`
+     - `skill-creator` — split/renamed → `create-agentic-skill` + `create-local-skill`
+     - `verify` — never a skill (native tool)
+     - `simplify` — never a skill (native tool)
+     - `schedule` — never a skill (native tool)
+   - Apply `--skill <slug>` before writing or reporting candidate rows when provided.
+
+3. Read conversation history:
+   - Read all existing default sources for the selected date range: `~/.claude/history.jsonl`, `~/.codex/history.jsonl`, and `~/.codex/sessions/**/*.jsonl`.
+   - Read optional user-provided history/export paths in addition to the defaults unless the user explicitly says to use only those paths.
+   - If a source is missing or unreadable, report it and continue with available sources.
+
+4. Normalize records into visible user prompt candidates only:
+   - Claude compact history: use visible user-facing fields such as `display`, timestamp, project, session ID, and directly pasted visible context such as `pastedContents`.
+   - Codex compact history: use prompt `text`, timestamp, session ID, and cwd/project metadata when available.
+   - Codex rich session JSONL: include user `response_item` records only when they are user-authored messages.
+   - Exclude hidden system instructions, hidden developer instructions, base prompts, tool output, tool arguments, assistant messages, unavailable model context, and generated summaries.
+
+5. Classify candidate confidence:
+   - High confidence: the visible user prompt begins with or clearly invokes `/skill-name`, `$skill-name`, or `You have the <skill> skill installed`.
+   - Medium confidence: the visible user prompt names a known skill and asks the agent to use it, but does not use command syntax.
+   - Low confidence: the prompt only loosely mentions a skill or workflow. Include it in the report, but never write it even when `--apply` is present.
+   - When a candidate's skill slug matches a legacy skill map entry, tag it as `legacy: true` in addition to its confidence level.
+
+6. Compare against existing prompt history:
+   - For each high- or medium-confidence candidate, inspect `prompts/<skill-slug>/`.
+   - Skip an existing identical prompt file when the preserved visible prompt text and required frontmatter already match.
+   - When a timestamp filename collides with different content, add a deterministic short session suffix while preserving the base `skill-prompt-YYYYMMDD-HHMMSS-<short-topic>` filename shape.
+
+7. Block likely secrets before writing:
+   - Before any `--apply` write, scan candidate prompt text for likely secrets such as API keys, bearer tokens, private keys, cookie/session tokens, password assignments, credential-bearing URLs, database URLs, and common provider token prefixes.
+   - If a candidate contains a likely secret, do not write it. Mark it as blocked in the report and ask the user for a sanitized prompt.
+
+8. Write outputs:
+   - In report-only mode, write a review artifact at `alignment/prompt-history-backfill-{topic}.html` following `ALIGNMENT-PAGE.md`, plus a concise chat summary.
+   - In `--apply` mode, create missing prompt files under `prompts/<skill-slug>/` for active skills, or under `prompts/legacy/<old-slug>/` for legacy skills.
+   - Legacy skill prompt files add `legacy: true` and optional `successor: <new-slug>` to their YAML frontmatter (successor is included when the legacy map has a renamed/split successor).
+   - Use this YAML frontmatter exactly for every backfilled prompt file: `skill`, `agent`, `captured_at`, `source`, and `prompt_scope: visible-user-invocation`.
+   - Use `source: user-invocation` unless the user explicitly requests a more specific visible source label; put history file paths and session IDs in the report, not in prompt frontmatter.
+   - Preserve the exact visible user prompt content after frontmatter without summarizing, redacting, or truncating.
+
+## Output
+
+The report should include:
+
+- Scope: repository, filters, sources read, sources missing, and mode.
+- Candidate summary by confidence, skill slug, source agent, timestamp, session ID, and status.
+- Missing prompt files that would be created in report-only mode.
+- Prompt files created in `--apply` mode.
+- Existing identical prompt files skipped.
+- Filename collisions and deterministic suffixes used.
+- Low-confidence candidates excluded from writes.
+- Likely-secret candidates blocked, with a sanitized-prompt request.
+- Verification notes proving no hidden system/developer/tool output was used and all prompt writes stayed under `prompts/<skill-slug>/`.
+
+## Constraints
+
+- Report-only is the safe default; `--apply` is the only write mode for prompt files.
+- Never write low-confidence candidates.
+- Never write likely-secret candidates.
+- Never write prompt files outside `prompts/<skill-slug>/` (active skills) or `prompts/legacy/<old-slug>/` (legacy skills).
+- `prompts/legacy/<old-slug>/` is the only valid write path for legacy skill prompts; never create top-level `prompts/<old-slug>/` directories for legacy skills.
+- Do not summarize, redact, or truncate the visible prompt body in backfilled prompt files.
+- Do not include hidden system/developer instructions, tool output, assistant messages, or unavailable model context in prompt files.
+- Do not create or modify GitHub Actions workflows.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/prompt-history-backfill-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/session-analytics/claude/session-triage/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 2026-06-12
+
+- Standardized active pack and skill install guidance on `npx skillpacks install <pack-or-skill>` instead of agent-native `/pack install` or `$pack install` recommendations.
+
 ## v0.0
 
 - Archived previous skill contract.

package/packs/session-analytics/claude/session-triage/SKILL.md

@@ -2,7 +2,7 @@
 name: session-triage
 description: Investigate one immediate session, correction, repo incident, or skill failure and recommend a verified fix
 type: analysis
-version: v0.1
+version: v0.2
 argument-hint: "[session id/file, repo path, skill name/path, correction text, or issue description]"
 ---
 
@@ -25,7 +25,7 @@ Use `/analyze-sessions` instead when the user wants broad cross-session trends,
 1. Define the investigation scope:
    - Treat the current conversation and current working directory as the default scope.
    - Prefer user-provided session IDs, files, repo paths, skill names, exact correction phrases, errors, logs, and test failures over broad history searches.
-   - Resolve named skills from `global/codex`, `global/claude`, `packs`, project-local `.agents`, `.codex`, `.claude`, and installed `~/.codex/skills` or `~/.claude/skills` as read-only fallback evidence.
+   - Resolve named skills from `base/codex`, `base/claude`, `packs`, project-local `.agents`, `.codex`, `.claude`, and installed `~/.codex/skills` or `~/.claude/skills` as read-only fallback evidence.
    - Do not create an `/analyze-session` alias or route; use this distinct command name to avoid singular/plural confusion.
 
 2. Gather narrow evidence first:
@@ -85,7 +85,7 @@ Produce a structured report with:
 - Do not create or suggest `/analyze-session`; use `/session-triage`.
 - Do not create or modify GitHub Actions workflows.
 - If a source is missing or unreadable, report that clearly and continue with available evidence instead of guessing.
-- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `npx skillpacks install <pack-name>` to the recommendation.
 
 ## Default Shipping Contract
 

package/packs/session-analytics/claude/session-triage/archive/v0.1/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: session-triage
+description: Investigate one immediate session, correction, repo incident, or skill failure and recommend a verified fix
+type: analysis
+version: v0.1
+argument-hint: "[session id/file, repo path, skill name/path, correction text, or issue description]"
+---
+
+# Session Triage
+
+Use this skill when the user wants a focused investigation of one immediate issue: a current conversation problem, one correction, one session, one repo incident, one failed run, or one suspected skill failure. This skill verifies what happened before recommending a durable fix.
+
+Use `/analyze-sessions` instead when the user wants broad cross-session trends, recurring frustration analysis, performance evaluation over time, repeated prompt patterns, or automation opportunities.
+
+## Inputs
+
+- Active conversation context.
+- Optional session ID, session file, or exported log.
+- Optional repository path or current working directory.
+- Optional skill name or `SKILL.md` path.
+- Optional user correction text, error output, test failure, log excerpt, file path, commit, or issue description.
+
+## Process
+
+1. Define the investigation scope:
+   - Treat the current conversation and current working directory as the default scope.
+   - Prefer user-provided session IDs, files, repo paths, skill names, exact correction phrases, errors, logs, and test failures over broad history searches.
+   - Resolve named skills from `global/codex`, `global/claude`, `packs`, project-local `.agents`, `.codex`, `.claude`, and installed `~/.codex/skills` or `~/.claude/skills` as read-only fallback evidence.
+   - Do not create an `/analyze-session` alias or route; use this distinct command name to avoid singular/plural confusion.
+
+2. Gather narrow evidence first:
+   - Read the target skill contract when a skill is named.
+   - Read directly relevant project instructions such as `AGENTS.md`, `CLAUDE.md`, task docs, pack docs, logs, or test output.
+   - Search only the scoped repo/session/history for the issue text, skill name, invocation command, relevant file paths, user correction, and nearby agent actions.
+   - Include the active conversation as evidence when the correction is happening now.
+   - Broaden to `/analyze-sessions` only when recurrence, frequency, or trend evidence is needed.
+
+3. Verify the issue before diagnosing:
+   - Separate the **user-identified issue** from the **agent-verified issue**.
+   - Classify the verification verdict as `verified`, `partially verified`, `not verified`, or `inconclusive`.
+   - A verified issue requires evidence for what the agent did, what the skill/repo/user contract required, and why the outcome was wrong or risky.
+   - If evidence shows the skill contract was adequate and the agent ignored it, say that directly.
+
+4. Build a concise timeline:
+   - User request or trigger.
+   - Skill or instruction that should have applied.
+   - Agent action or omission.
+   - Failure, correction, or observed impact.
+   - Relevant repo/session state.
+
+5. Diagnose root cause:
+   - Identify whether the cause is a missing trigger, ambiguous trigger, missing evidence gate, insufficient scope resolution, weak output contract, bad next-step routing, missing validation, missing safety constraint, stale mirrored contract, repo instruction conflict, or agent noncompliance with an adequate contract.
+   - Compare Claude and Codex skill versions when both exist and flag mirrored drift.
+   - Check `tasks/lessons.md` when working in `agentic-skills`; reuse existing lessons or recommend a new lesson when the pattern is novel.
+   - For benchmark failures, check recent same-skill `benchmark/triage-<skill>-*.md` reports and `tasks/lessons.md` before recommending a narrow tolerance patch. If two or more recent reports classify the same family of valid outputs as benchmark false negatives, stop patching individual phrasings and route to a generalized rubric, semantic evaluator, fixture-family, or infrastructure-classifier fix that covers the family.
+
+6. Recommend the smallest durable fix:
+   - Name exact skill file(s), instruction file(s), or docs to change.
+   - Provide concrete rule text or workflow-step wording when a skill-contract change is justified.
+   - Include validation checks that prove the revised behavior prevents the issue, such as targeted `rg` checks, mirrored contract checks, version checks, replay of the decision path, or the failing test/log command.
+   - For repeated benchmark false-negative families, the recommended fix must name the owning harness or setup file, the family-level behavior to recognize or reject, positive and negative fixture shapes to add, and a validation command such as focused layer1 setup tests plus `pnpm --dir tests verify --skill <skill>`.
+   - Route verified skill changes to `/targeted-skill-builder` (skill-dev pack) for a narrow update or `/create-agentic-skill` (skill-dev pack) for a new repo-managed skill.
+
+## Output
+
+Produce a structured report with:
+
+- Target: session/repo/skill scope and evidence sources.
+- User-identified issue: the user's claim in concise terms.
+- Verification verdict: `verified`, `partially verified`, `not verified`, or `inconclusive`, with supporting evidence.
+- Timeline: short sequence from trigger to correction or impact.
+- Root cause: the specific contract gap, repo conflict, or agent noncompliance pattern.
+- Responsible contract gap: skill, project instruction, task doc, or none.
+- Recommended fix: exact file(s), section(s), and proposed wording or behavior change.
+- Validation plan: commands or checks to prove the fix.
+- Confidence and evidence gaps: what is known, what could not be verified, and whether `/analyze-sessions` is needed for recurrence analysis.
+- Recommended next skill: `/targeted-skill-builder` (skill-dev pack), `/create-agentic-skill` (skill-dev pack), `/analyze-sessions`, or `none` when no follow-up is justified.
+
+## Constraints
+
+- Start narrow and evidence-bound; do not scan all local history by default.
+- Do not claim a user-identified issue is agent-verified without independent evidence.
+- Do not modify the target skill during analysis unless the user also asked for implementation and the active workflow permits edits.
+- Do not recommend a skill change when the evidence points only to one-off agent noncompliance and the contract is already clear.
+- Do not create or suggest `/analyze-session`; use `/session-triage`.
+- Do not create or modify GitHub Actions workflows.
+- If a source is missing or unreadable, report that clearly and continue with available evidence instead of guessing.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `/pack install <pack-name>` to the recommendation.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.