@laitszkin/apollo-toolkit 2.0.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS Guide
+
+## Project Architecture
+
+- This repository is a skill catalog: each top-level skill lives in its own directory and is installable when that directory contains `SKILL.md`.
+- Typical skill layout is lightweight and consistent: `SKILL.md`, `README.md`, `LICENSE`, plus optional `agents/`, `references/`, and `scripts/`.
+- The npm package exposes an `apollo-toolkit` CLI that stages a managed copy under `~/.apollo-toolkit` and links each skill folder into selected target directories.
+- `scripts/install_skills.sh` and `scripts/install_skills.ps1` remain available for local/curl installs and mirror the managed-home linking behavior.
+
+## Core Business Flow
+
+This repository enables users to install and run a curated set of reusable agent skills for software delivery, research, repository maintenance, and media-generation workflows.
+
+- Users can align project documentation with the current codebase.
+- Users can consolidate accumulated project specs into a standardized README and categorized project documentation set.
+- Users can investigate application logs and produce evidence-backed root-cause findings.
+- Users can answer repository-backed questions with additional web research when needed.
+- Users can commit and push local changes without performing version or release work.
+- Users can research a topic deeply and produce evidence-based deliverables.
+- Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
+- Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.
+- Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to link.
+- Users can design and implement new features through a spec-first workflow.
+- Users can generate shared feature spec, task, and checklist planning artifacts for approval-gated workflows.
+- Users can convert text or documents into audio files with subtitle timelines.
+- Users can extend existing features in a brownfield codebase with required tests and approvals.
+- Users can propose product features from an existing codebase and publish accepted proposals.
+- Users can discover reproducible edge-case risks and report prioritized hardening gaps.
+- Users can fix remote GitHub issues locally and submit the resulting pull requests.
+- Users can run evidence-first application security audits focused on confirmed vulnerabilities.
+- Users can learn new or improved skills from recent Codex conversation history.
+- Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
+- Users can summarize mistakes into a learning error book and render it to PDF.
+- Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.
+- Users can turn novel content into a loopable short-form video with generated assets.
+- Users can publish structured GitHub issues or feature proposals with auth fallbacks.
+- Users can prepare and open open-source pull requests from existing changes.
+- Users can generate storyboard image sets from chapters, novels, articles, or scripts.
+- Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
+- Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
+- Users can process GitHub pull request review comments and resolve addressed threads.
+- Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
+- Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
+- Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.
+- Users can generate 30-60 second short videos directly from text prompts.
+- Users can prepare and publish versioned releases with changelog and tag workflows.
+- Users can generate long-form videos by orchestrating storyboard, voice, and Remotion-based production steps.
+
+## Core Project Purpose
+
+- Provide a curated set of reusable agent skills that can be installed into Codex/OpenClaw/Trae skill directories.
+- Keep skills focused, composable, and easy to reuse across workflows.
+- Prefer splitting shared capabilities into dedicated skills when multiple workflows can depend on them.
+
+## Code Style And Conventions
+
+- Follow existing skill naming: kebab-case folder names and matching `name` values in `SKILL.md` frontmatter.
+- Keep documentation concise, operational, and evidence-based; avoid speculative guidance.
+- Reuse existing patterns from neighboring skills before introducing new structures.
+- Use a standardized `## Dependencies` section in every `SKILL.md` with `Required`, `Conditional`, `Optional`, and `Fallback` bullets whenever skill-to-skill orchestration matters.
+- Use a standardized `## Standards` section in every `SKILL.md` with `Evidence`, `Execution`, `Quality`, and `Output` bullets to summarize skill-specific constraints.
+- Keep helper scripts small and deterministic, and update repository docs when adding or moving a top-level skill.

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this repository are documented in this file.
+
+## [Unreleased]
+
+## [v2.0.0] - 2026-03-17
+
+### Added
+- Add the `@laitszkin/apollo-toolkit` npm package with an `apollo-toolkit` CLI entrypoint.
+- Add an interactive terminal installer with Apollo Toolkit branding, multi-target selection, and managed installs under `~/.apollo-toolkit`.
+- Add Node-based installer tests and a release-triggered npm Trusted Publishing workflow.
+
+### Changed
+- Change managed installer defaults from `~/.apollo-toolkit-repo` to `~/.apollo-toolkit` for curl / iwr installs.
+- Refresh installer documentation around npm, npx, and global CLI usage.
+
+## [v1.1.0] - 2026-03-13
+
+### Added
+- Add `deep-research-topics` for evidence-based research deliverables.
+- Add `review-codebases` for repository-wide code review and issue publication workflows.
+- Add `agents/openai.yaml` metadata across top-level skills.
+- Add skill metadata validation scripts and a GitHub Actions workflow for `SKILL.md` frontmatter and `agents/openai.yaml`.
+- Add `harden-app-security/references/common-software-attack-catalog.md` for broader security audit coverage.
+
+### Changed
+- Expand `harden-app-security` into a discovery-only adversarial audit workflow with broader common software attack coverage.
+- Strengthen `develop-new-features`, `enhance-existing-features`, `discover-edge-cases`, and related references with clearer testing and evidence requirements.
+- Refresh root and skill-level documentation to reflect the new skills, metadata requirements, and review workflow guidance.
+
+### Fixed
+- Restore skill metadata loading behavior after the OpenAI agent metadata rollout.
+
+## [v1.0.0] - 2026-03-09
+
+### Added
+- Add `align-project-documents` for codebase-driven project documentation alignment.
+- Add `answering-questions-with-research` for evidence-based answers that combine repo discovery with web research.
+- Add `learning-error-book` for mistake summaries with Markdown-to-PDF error book generation.
+- Add `maintain-project-constraints` to keep `AGENTS.md` aligned with the repository.
+- Add `open-github-issue` for deterministic GitHub issue publishing with auth fallback and README-based language detection.
+- Add `resolve-review-comments` for PR review thread triage, adoption decisions, and resolution workflows.
+- Add cross-platform installers in `scripts/install_skills.sh` and `scripts/install_skills.ps1`.
+
+### Changed
+- Rename multiple skills for clearer naming, including `project-doc-aligner` -> `align-project-documents`, `agents-md-maintainer` -> `maintain-project-constraints`, `edge-case-test-fixer` -> `fix-edge-cases`, `github-issue-fix-pr-workflow` -> `fix-github-issues`, `gh-pr-review-comment-workflow` -> `resolve-review-comments`, `security-expert-hardening` -> `harden-app-security`, and `app-log-issue-analysis` -> `analyse-app-logs`.
+- Split GitHub issue publication out of `analyse-app-logs` and make it depend on `open-github-issue`.
+- Expand `open-github-issue` with target repository resolution, README-based language selection, and deterministic draft fallback behavior.
+- Strengthen `develop-new-features`, `enhance-existing-features`, and related skills with clearer property-based testing requirements and refreshed templates.
+- Move installer entrypoints into `scripts/`, add Trae install support, and improve curl/pipe repo detection.
+- Refresh root and skill-level docs to reflect the renamed skills, installer flow, and dependency guidance.
+
+### Fixed
+- Correct current documentation references to `maintain-project-constraints`.
+
+## [v0.6.0] - 2026-02-27
+
+### Added
+- Add default worktree guidance to `github-issue-fix-pr-workflow` debug dependencies.
+
+### Changed
+- Quote a multiline skill description in `systematic-debug` to keep YAML metadata valid.
+- Refine `systematic-debug` auto-invoke criteria and examples for mismatched behavior debugging.
+- Clarify `version-release` workflow requirements for release range review and code/documentation alignment.
+
+## [v0.5.0] - 2026-02-26
+
+### Added
+- Add `commit-and-push` skill for commit+push-only submission workflows.
+- Add `version-release` skill for explicit version/tag/changelog release workflows.
+- Add new skill documents and references for the split submit/release workflows.
+
+### Changed
+- Replace legacy `submit-changes` with two dedicated skills: `commit-and-push` and `version-release`.
+- Translate project documentation, templates, and testing/reference guides to English across skills.
+- Update multiple skill definitions to English wording for consistent skill documentation language.
+- Clarify spec-first requirements in feature-planning skills, including mandatory re-approval after clarification updates.
+
+## [v0.4.0] - 2026-02-26
+
+### Added
+- Add `github-issue-fix-pr-workflow` skill with issue listing, local fix flow, and PR submission guidance.
+- Add `github-issue-fix-pr-workflow/scripts/list_issues.py` and related tests for deterministic issue discovery.
+
+### Changed
+- Update `install_skills.sh` to support interactive multi-option selection, multi-mode CLI input, and `all` installation.
+- Add Trae IDE support in `install_skills.sh`, with a default install target at `~/.trae/skills`.
+- Update root `README.md` installer examples to include `trae` and `all` usage.
+- Highlight BDD keywords in `develop-new-features` and `enhance-existing-features` spec templates using Markdown bold formatting.
+
+## [v0.3.0] - 2026-02-25
+
+### Added
+- Enhance `app-log-issue-analysis` with deterministic GitHub issue publishing support.
+- Add `app-log-issue-analysis/scripts/publish_log_issue.py` for issue publishing with auth fallback (`gh` login -> `GITHUB_TOKEN`/`GH_TOKEN` -> draft).
+- Add remote README-based issue language selection (Chinese README -> Chinese issue body, otherwise English).
+
+### Changed
+- Update app-log issue analysis docs, checklist, and default prompt to document the new issue publishing workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Apollo Toolkit Skills
+
+A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer that keeps the toolkit in `~/.apollo-toolkit` and links each skill into the targets you choose.
+
+## Included skills
+
+- align-project-documents
+- analyse-app-logs
+- answering-questions-with-research
+- commit-and-push
+- deep-research-topics
+- develop-new-features
+- discover-edge-cases
+- docs-to-voice
+- enhance-existing-features
+- feature-propose
+- financial-research
+- fix-github-issues
+- generate-spec
+- harden-app-security
+- improve-observability
+- learn-skill-from-conversations
+- learning-error-book
+- maintain-project-constraints
+- maintain-skill-catalog
+- novel-to-short-video
+- open-github-issue
+- open-source-pr-workflow
+- openai-text-to-image-storyboard
+- record-spending
+- resolve-review-comments
+- review-change-set
+- review-codebases
+- specs-to-project-docs
+- systematic-debug
+- text-to-short-video
+- version-release
+- video-production
+- weekly-financial-event-report
+
+## Install with npm or npx
+
+### Recommended
+
+```bash
+npx @laitszkin/apollo-toolkit
+```
+
+The interactive installer:
+- shows an `Apollo Toolkit` terminal screen
+- installs a managed copy into `~/.apollo-toolkit`
+- lets you multi-select `codex`, `openclaw`, `trae`, or `all`
+- creates symlinks from `~/.apollo-toolkit/<skill>` into each selected target
+
+### Global install
+
+```bash
+npm i -g @laitszkin/apollo-toolkit
+apollo-toolkit
+```
+
+### Non-interactive install
+
+```bash
+npx @laitszkin/apollo-toolkit codex
+npx @laitszkin/apollo-toolkit codex openclaw
+npx @laitszkin/apollo-toolkit all
+```
+
+### Optional overrides
+
+```bash
+APOLLO_TOOLKIT_HOME=~/custom-toolkit npx @laitszkin/apollo-toolkit codex
+CODEX_SKILLS_DIR=~/custom-codex-skills npx @laitszkin/apollo-toolkit codex
+OPENCLAW_HOME=~/.openclaw npx @laitszkin/apollo-toolkit openclaw
+TRAE_SKILLS_DIR=~/.trae/skills npx @laitszkin/apollo-toolkit trae
+```
+
+## Local installer scripts
+
+Installers still live in `scripts/` for local repository usage and curl / iwr installation:
+
+- macOS/Linux: `scripts/install_skills.sh`
+- Windows (PowerShell): `scripts/install_skills.ps1`
+
+### Local usage
+
+```bash
+./scripts/install_skills.sh
+./scripts/install_skills.sh codex
+./scripts/install_skills.sh openclaw
+./scripts/install_skills.sh trae
+./scripts/install_skills.sh all
+```
+
+```powershell
+./scripts/install_skills.ps1
+./scripts/install_skills.ps1 codex
+./scripts/install_skills.ps1 all
+```
+
+### Curl / iwr one-liners
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash
+curl -fsSL https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.sh | bash -s -- codex
+```
+
+```powershell
+irm https://raw.githubusercontent.com/LaiTszKin/apollo-toolkit/main/scripts/install_skills.ps1 | iex
+```
+
+In curl / iwr mode, the scripts clone or update the managed toolkit copy under `~/.apollo-toolkit` by default. Override with `APOLLO_TOOLKIT_HOME` if you need a different location.
+
+## External dependency skills
+
+The install commands below were checked with the Skills CLI unless otherwise noted.
+
+| Skill name | Used by | Author / producer | Install command / note |
+| --- | --- | --- | --- |
+| `pdf` | `deep-research-topics`, `financial-research`, `learning-error-book`, `weekly-financial-event-report` | OpenAI (`openai/skills`) | `npx skills add openai/skills@pdf -g -y` |
+| `doc` | `deep-research-topics` (optional Word output) | OpenAI (`openai/skills`) | `npx skills add openai/skills@doc -g -y` |
+| `slides` | `deep-research-topics` (optional slide output) | OpenAI (`openai/skills`) | `npx skills add openai/skills@slides -g -y` |
+| `spreadsheet` | `record-spending` | OpenAI (`openai/skills`) | `npx skills add openai/skills@spreadsheet -g -y` |
+| `skill-creator` | `learn-skill-from-conversations` | OpenAI (`openai/skills`) | `npx skills add openai/skills@skill-creator -g -y` |
+| `remotion-best-practices` | `novel-to-short-video`, `video-production` | Remotion (`remotion-dev/skills`) | `npx skills add remotion-dev/skills@remotion-best-practices -g -y` |
+| `code-simplifier` | `open-source-pr-workflow` | Sentry (`getsentry/skills`) | `npx skills add getsentry/skills@code-simplifier -g -y` |
+
+Compatibility note:
+
+- `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`.
+- `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
+- `fix-github-issues` accepts `open-source-pr-workflow` or an environment alias named `open-pr-workflow`. Apollo Toolkit already vendors `open-source-pr-workflow`, so `open-pr-workflow` is not a required external dependency here.
+
+## Release publishing
+
+GitHub Releases can publish the npm package automatically through npm Trusted Publishing.
+
+Before the workflow can succeed, configure the npm package to trust this GitHub repository and the publish workflow. After that, creating a GitHub Release will trigger `.github/workflows/publish-npm.yml` and run `npm publish --provenance --access public`.
+
+## Notes
+
+- This repository is intended for personal toolkit curation and experimentation.
+- Skill folders are stored as regular files, not git submodules.

package/align-project-documents/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: align-project-documents
+description: Read and understand a software project, then generate or align project documentation with the current codebase. Use when a user asks for project docs (usage, technical architecture, debugging flow, setup, operations) or asks to verify and sync existing documentation with real implementation.
+---
+
+# Align Project Documents
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Treat source code, configuration, scripts, and tests as the source of truth.
+- Execution: Discover project facts before choosing generate mode or align mode.
+- Quality: Keep every non-trivial claim traceable and remove stale documentation instead of appending around it.
+- Output: Write concise, operator-friendly docs with runnable commands and clear section structure.
+
+## Goal
+
+Produce accurate, code-grounded project documentation. Prefer evidence from source code, configs, scripts, and tests over assumptions.
+
+## Workflow
+
+### 1) Discover project facts first
+
+- Read key files before writing: `README*`, `package.json`/`pyproject.toml`/`go.mod`, lock files, CI configs, entrypoints, and test setup.
+- Inspect main runtime paths (API/server, worker, frontend, CLI, jobs) and dependency boundaries.
+- Build a factual map: startup commands, environment variables, request/data flow, major modules, external integrations, and observability points.
+- Record concrete evidence with file paths for every important claim.
+
+### 2) Decide documentation mode
+
+- **Generate mode**: no usable docs exist, or user asks to create docs from scratch.
+- **Align mode**: existing docs exist and must be checked against implementation.
+
+### 3) Generate mode output
+
+Create or update documentation with at least these sections:
+
+1. Project Overview
+2. Quick Start / Local Run
+3. Usage Guide (common workflows and commands)
+4. Technical Architecture (components, boundaries, data flow)
+5. Configuration and Environment Variables
+6. Debugging Playbook (symptom -> checks -> likely root cause -> fix path)
+7. Testing and Validation
+8. Deployment or Runtime Notes (if applicable)
+
+Writing rules:
+
+- Write what is true now, not what should be true.
+- Use concrete commands and paths from the repository.
+- Keep examples executable when possible.
+- Call out unknowns explicitly instead of guessing.
+
+### 4) Align mode output
+
+When docs already exist:
+
+1. Enumerate existing docs and their scope.
+2. Compare each claim against current code and scripts.
+3. Classify findings:
+   - **Accurate**
+   - **Outdated**
+   - **Missing**
+   - **Ambiguous**
+4. Update docs to match real behavior.
+5. Add a short "Documentation Delta" summary listing major corrections.
+
+Alignment checklist:
+
+- Startup/install commands still work.
+- Directory/module names match current tree.
+- API/routes/events/messages match implementation.
+- Config keys and env vars match code usage.
+- Debug instructions reference real logs, metrics, and breakpoints.
+- Test commands and expected outputs are current.
+
+## Quality Gate (must pass before finishing)
+
+- Ensure every non-trivial statement is traceable to repository evidence.
+- Ensure usage and debug steps are reproducible from current code.
+- Ensure architecture description reflects actual module boundaries.
+- Ensure outdated statements are removed, not only appended.
+
+## Output Style
+
+- Write concise, operator-friendly documentation.
+- Use headings, short bullets, and runnable command snippets.
+- Prefer direct language and avoid speculative wording.

package/align-project-documents/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Align Project Documents"
+  short_description: "Generate or sync project docs against the real codebase"
+  default_prompt: "Use $align-project-documents to inspect the repository first, ground every claim in code/config/test evidence, then generate or align project documentation covering usage, architecture, configuration, debugging, testing, and runtime notes without guessing."

package/analyse-app-logs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/analyse-app-logs/README.md

@@ -0,0 +1,126 @@
+# Analyse App Logs
+
+An agent skill for evidence-driven application log investigations.
+
+This skill helps agents analyze logs end-to-end, correlate runtime signals with code paths, and produce actionable incident findings with confidence levels and remediation steps.
+
+## What this skill provides
+
+- A structured workflow for incident investigation from scoping to remediation.
+- A bias toward bounded, recent log windows so stale history does not contaminate conclusions.
+- A strict evidence standard (log lines + code correlation + impact + confidence).
+- A checklist to avoid false conclusions.
+- A pattern catalog for common operational failures (timeouts, retry storms, auth errors, resource pressure, schema mismatch, race conditions, and dependency outages).
+- GitHub issue publication via the `open-github-issue` dependency skill.
+- Issue language selection delegated to `open-github-issue` based on the target repository README: Chinese README -> localized issue body, otherwise English issue body.
+
+## Repository structure
+
+- `SKILL.md`: Main skill definition, principles, and output format.
+- `agents/openai.yaml`: Agent interface metadata and default prompt.
+- `references/investigation-checklist.md`: Investigation validation checklist.
+- `references/log-signal-patterns.md`: Log signal pattern reference.
+- Dependency skill: `open-github-issue` for deterministic issue publishing.
+
+## Installation
+
+1. Clone this repository.
+2. Copy this folder to your Codex skills directory:
+
+```bash
+mkdir -p "$CODEX_HOME/skills"
+cp -R analyse-app-logs "$CODEX_HOME/skills/analyse-app-logs"
+```
+
+## Usage
+
+Invoke the skill in your prompt:
+
+```text
+Use $analyse-app-logs to inspect these logs and identify root causes.
+```
+
+Issue publication behavior for each confirmed finding:
+
+1. Prepare a structured issue handoff from the confirmed log finding.
+2. Delegate publication to `$open-github-issue`.
+3. Reuse the dependency result in the final publication status section.
+
+Each delegated issue must still include exactly three sections:
+
+- `Problem Description`
+- `Suspected Cause`
+- `Reproduction Conditions (if available)`
+
+For localized repositories, `open-github-issue` uses translated section titles with the same meaning.
+
+Best results come from including:
+
+- Service/component name
+- Environment (prod/staging/dev)
+- Incident time window (with timezone)
+- If the window is unknown, a concrete runtime boundary such as the last container restart, latest deploy, worker boot, or first observed failure after a healthy period
+- Correlation IDs (trace/request/job/user/tx)
+- Relevant log excerpts and recent deploy/config context
+
+When the time window is not explicitly provided, the skill should first derive a bounded analysis window from a recent concrete event, such as the last container restart, and inspect only that slice before widening the search.
+
+## Example
+
+### Input prompt
+
+```text
+Use $analyse-app-logs to investigate this production incident.
+
+Service: payment-api
+Environment: prod
+Time window: 2026-02-05 09:10 UTC to 2026-02-05 09:25 UTC
+
+Logs:
+2026-02-05T09:11:03Z WARN request_id=ab12 retry=1 upstream request timed out endpoint=/charge
+2026-02-05T09:11:05Z WARN request_id=ab12 retry=2 upstream request timed out endpoint=/charge
+2026-02-05T09:11:07Z ERROR request_id=ab12 deadline exceeded endpoint=/charge
+```
+
+### Expected response shape
+
+```text
+1) Incident summary
+- payment-api in prod shows repeated timeout escalation between 09:11:03 and 09:11:07 UTC.
+
+2) Confirmed issues
+- Symptom: escalating retries followed by deadline exceeded on /charge.
+- Log evidence: request_id=ab12 has two timeout warnings then one terminal error in 4 seconds.
+- Code correlation: correlate timeout path in request handler and upstream client call site.
+- Root cause analysis: likely dependency latency spike with insufficient retry backoff.
+- Impact: charge attempts fail for affected requests during the window.
+- Recommended remediation: add bounded exponential backoff with jitter and tighten timeout budgets.
+
+3) Hypotheses and required validation
+- Check upstream latency metrics and connection pool saturation for the same window.
+
+4) Monitoring and prevention improvements
+- Add alert on timeout-rate spike and include upstream host + timeout budget fields in logs.
+
+5) GitHub issue publication status
+- Mode: gh-cli
+- Created: https://github.com/<owner>/<repo>/issues/123
+```
+
+## Output expectations
+
+The skill is designed to return:
+
+1. Incident summary (scope, timeframe, overall status)
+2. Confirmed issues ordered by severity
+3. Hypotheses (when evidence is incomplete) with required validation data
+4. Monitoring and prevention improvements
+5. GitHub issue publication status (mode, created URLs, or drafts + reason)
+
+## Development notes
+
+This repository is intentionally lightweight and focused on reusable investigation guidance.
+
+## License
+
+MIT. See `LICENSE`.