understand-project-yylo

Inspect product architecture, dependencies, and validation loops before planning or implementing a requested change with YYLO.

task-management
workflow
coding-agents
ledger
project-planning

SKILL.md

GitHub

Understand the project

  1. Read AGENTS.md/CLAUDE.md, repository status, relevant source, tests, and existing product documentation in the integration or assigned feature worktree.
  2. Read related Kanban tasks and durable specs through the canonical metadata controller. Do not assume .juno_task/plan.md exists and do not materialize controller-private metadata in a product worktree.
  3. Trace only the dependencies and runtime paths needed for the requested goal. Use bounded parallel investigation when independent questions justify it.
  4. Report current behavior, sources of truth, affected components, risks, unknowns, and the smallest useful validation loop.
  5. If the user requested planning, hand the findings to plan-ledger-tasks-yylo. If implementation was requested, work only in the task worktree returned by yy task start TASK_ID.
  6. Write a durable operational spec only when requested or materially useful. Draft it externally, preflight the installed yy ledger artifact API, capture it as an immutable report Artifact Record with provenance/retention, and verify retrieval, digest, and history. If that API is unavailable, stop with the external draft intact; never fall back to product docs/, task bodies/responses, new .juno_task/specs, or direct controller-store edits. Product docs/ remains reserved for documentation shipped with the product. Do not update root instructions with transient status.

Retrieve context without guessing types

Preflight yy ledger get --help; prefer yy ledger get RECORD_ID -f json for known task, document, PDR or artifact IDs. If installed get is task-only, use yy ledger record get RECORD_ID -f json after checking native help; stop for an upgrade if unavailable. New generated IDs use task_, doc_, or artifact_ for storage kind; existing IDs remain unchanged. New PDRs are artifact/report; historical document/pdr Records remain readable without reclassification.

When no ID is known, use yy ledger record search --projection summary --limit 20 -f json. Exact reads include hot and archived Records in the selected project; discovery is hot-only unless archive scope is explicit. Preserve missing/ambiguous/corrupt record diagnostics rather than trying other kinds or projects. Universal get includes small readable UTF-8 content up to 64 KiB; metadata with omitted content is not payload evidence. Use explicit bounded --content for local/inline bytes (maximum 16 MiB), check exit status, and never implicitly fetch external URLs.

User-facing Record results

After creation, update, discovery, or handoff, report the Record kind/profile, actual immutable Record ID, and actual Ledger slug from the returned Record or a native get readback. Never invent a slug from the title or confuse it with the ID. If the selected API omits a field, say it is unavailable rather than fabricate it. IDs remain authoritative for relations and lifecycle operations; slugs aid discovery.

Invocation contract

The structured views below intentionally alias parts of the complete request; they are not additional user arguments.

Main task

$1

Constraints and context

$2

Complete raw request

$ARGUMENTS