scopone/.github/skills/append-log/SKILL.md

---
name: append-log
description: Appends a structured JSON log entry to the pipeline log file. Use this skill whenever a Log instruction appears in the Orchestrator.
argument-hint: event=<name> message=<text> iteration=<n|null> task_id=<id|null> parallel_group=<id|null>
---

# Append Log

## Log File

Path: `prompts/{jira}/log.jsonl` — use absolute path always.

## Instruction: `append-log`

`append-log` is a SKILL procedure. Skills provide instructions; tools execute actions.

Use available timestamp and file-edit tools to execute this procedure.

If logging fails, treat it as a loading/configuration issue (skill loading, tool availability, or path mismatch), not as permission to bypass logging.

When you see `Log:` followed by an event name, do these steps:

### Step 1: Get Timestamp

Follow the [timestamp](../timestamp/SKILL.md) skill to get `{ISO8601}`.

### Step 2: Build JSON Line

{"timestamp":"{ISO8601}","level":"{level}","agent":"Orchestrator","event":"{event}","iteration":{iteration},"task_id":{task_id},"parallel_group":{parallel_group},"message":"{message}"}

- `level`: `"INFO"` (default) or `"ERROR"`
- `iteration`: integer or `null`
- `task_id`: `"TASK-X"` or `null`
- `parallel_group`: `"A"` or `null`

### Step 2.5: Violation Detection

If `message` contains "ERROR.*violates.*rule" or "FORBIDDEN.*action" or "ROLE VIOLATION":
  Set `level`: `"CRITICAL_VIOLATION"`
  Add field: `"role_violation": true`

### Step 3: Append to File

Use deterministic file operations:

1. Resolve absolute path: `{absolute_path}/prompts/{jira}/log.jsonl`.
2. If file does not exist, create it with exactly `{json_line}\n`.
3. If file exists, append exactly one newline-terminated JSON line at end of file using the available edit mechanism for the environment.
4. Preserve existing content verbatim; never rewrite prior entries except appending at EOF.

Implementation guidance by capability:
- If a direct append API exists, use it.
- Otherwise read current content and write back `existing_content + "\n" + json_line + "\n"` (avoid duplicate blank lines).
- Prefer file-edit tools over terminal commands.

### Step 4: Diagnostics Before Fallback

Before any fallback behavior, verify:
1. Skill discovery works (skill folder and frontmatter `name` are both `append-log`).
2. Skill loading is enabled and visible in chat customization diagnostics.
3. Required file-edit tools are available to the active agent.

If diagnostics indicate missing skill loading/configuration, STOP and report the configuration issue explicitly.

## Example

First `Log:` creates the file:

create_file( filePath = "F:/project/prompts/CACTUS-1234/log.jsonl", content = '{"timestamp":"2026-02-11T14:30:00.000Z","level":"INFO","agent":"Orchestrator","event":"orchestrator.start","iteration":null,"task_id":null,"parallel_group":null,"message":"Pipeline started for CACTUS-1234"}\n' )

Second `Log:` appends a new line to the same file:

Pseudocode (tool names vary by environment):

read current file content

append one JSON line at EOF

write back without altering previous lines