=====
Usage
=====

This guide covers how to use skills from the ``llm-workflow`` plugin in your
Claude Code sessions.

Invoking Skills
---------------

Skills can be triggered in several ways:

Automatic Triggering
^^^^^^^^^^^^^^^^^^^^

Skills are designed to trigger automatically when Claude detects a relevant
context. Each skill has trigger conditions defined in its description.

For example, the ``code-review-response`` skill triggers when you mention:

- Processing ISSUE comments
- Code review responses
- Reviewing code with ISSUE markers

Simply describe what you want to do:

.. code-block:: text

   > Process the ISSUE comments in my code

   > Find all the code review issues and generate a report

Explicit Invocation
^^^^^^^^^^^^^^^^^^^

You can explicitly invoke a skill using the slash command syntax:

.. code-block:: text

   > /wf:code-review-response
   > /wf:council
   > /wf:debate
   > /wf:pre-mortem
   > /wf:review-tests
   > /wf:team-review-tests

This ensures the skill is used regardless of automatic trigger detection.

The ``debate`` skill also supports trigger phrases like "debate this",
"argue both sides", "devil's advocate", or "stress test this decision".

The ``council`` skill triggers on "council review", "multi-judge review",
or "council this plan".

The ``pre-mortem`` skill triggers on "pre-mortem", "failure analysis",
"risk analysis", or "what could go wrong".

The ``review-tests`` skill triggers on "review tests", "audit tests",
"test gaps", or "test cheating".

The ``team-review-tests`` skill triggers on "team review tests",
"team test review", "team audit tests", or "multi-judge test review".

Skill Output
------------

Each skill produces specific outputs. See the individual skill documentation
for details on what each skill generates.

Common output patterns:

- **Reports** - Markdown files in the skill-specific ``resources/``
  subdirectories
- **Transcripts** - Debate transcripts in ``resources/agent-docs/reviews/debates/``
- **Council reports** - Verdict reports in ``resources/agent-docs/reviews/councils/``
- **Pre-mortem reports** - Risk registers in ``resources/agent-docs/reviews/pre-mortems/``
- **Test review reports** - Findings registers in ``resources/agent-docs/reviews/tests/``
- **Modified files** - Direct edits to source files
- **Console output** - Information displayed during execution

Default Input Files
-------------------

Generated skill artifacts use platform-specific default input files:

- Claude Code: ``.claude/<skill>.md``
- Codex: ``.codex/<skill>.md``
- OpenCode: ``.opencode/<skill>.md``
- Grok: ``.grok/<skill>.md``

Migrated skills also check the legacy ``.claude/<skill>.md`` path after the
platform default, so existing repositories keep working.

Working with Reports
--------------------

Several skills generate markdown reports for later processing. These reports
are designed to integrate with other tools:

- **Spec generation** - Reports can feed ``to-spec`` / ``to-slices`` in the slice loop
- **Documentation** - Reports serve as project documentation

Example Workflow
----------------

A typical code review workflow:

1. **Review code manually** - Add ``ISSUE:`` comments where you find problems

   .. code-block:: python

      # ISSUE: This function lacks error handling for empty input
      def process_data(items):
          return [transform(i) for i in items]

2. **Generate report** - Ask Claude to process the issues

   .. code-block:: text

      > Process the ISSUE comments in my codebase

3. **Review the report** - Check ``resources/agent-docs/reviews/code/code-review-1.md``

4. **Plan fixes** - Use the report to create a PRD or task list

5. **Implement** - Fix the validated issues

Tips
----

- **Be specific** - When invoking skills, provide context about what you want
- **Check outputs** - Review generated reports before acting on them
- **Iterate** - Skills can be run multiple times as you refine your approach