Cmon Understand

Produce a concise context packet containing:

1. The relevant area of the repo
2. Repo foundation state for the target area or target project directory
3. Existing durable artifacts that matter
4. Local patterns and neighboring implementation surfaces
5. Known constraints from AGENTS.md, README.md, and nearby docs
6. Prior learnings or solution docs worth reusing
7. Open uncertainties that still need clarification
8. A next-stage routing recommendation with justification
9. Packet readiness notes describing what the next stage must treat as fixed vs unresolved

Use templates/understand/understand-context-template.md as the default shared context shape.

Workflow

Stage 1: Determine scope

Start from:

• the task request
• explicit paths if provided
• templates/understand/understand-run-manifest-template.md when operator control is needed

Stage 2: Gather shared context

Read local instructions and relevant artifacts first:

• AGENTS.md
• relevant docs in docs/
• prior durable artifacts in:
  • docs/brainstorms/
  • docs/plans/
  • docs/solutions/
  • docs/architecture/

Inspect the relevant code area:

• entry points
• neighboring modules
• nearby tests

Recover prior knowledge explicitly:

• solution or pattern docs that already cover the topic
• prior brainstorms, designs, or plans that should shape the next stage
• repo-local patterns the next stage should follow instead of reinventing

Check repo foundation explicitly:

• does the target directory already exist
• is it already a git repository
• is this substantial enough that durable artifacts and code should be versioned from the start

If the target is a greenfield project directory and it is not yet a git repo, do not treat that as invisible context.

If the target directory is clearly intended to become a real project root for substantial tracked work, initializing git during cmon:understand is acceptable.

Stage 3: Dispatch lens observers

Dispatch in parallel:

• agents/understand/product-observer.md
• agents/understand/engineer-observer.md
• agents/understand/ops-observer.md

Use templates/understand/lens-invocation-template.md as the default wrapper for each observer call.

Stage 4: Synthesize

Pass the shared context and observer outputs into:

• agents/understand/understand-synthesizer.md

Use templates/understand/synthesizer-input-template.md as the default synthesis structure.

Stage 5: Validate the packet

Before handoff, verify the packet is strong enough for the next stage:

• the relevant repo area is verified rather than guessed
• the strongest prior artifacts are named
• the most relevant local patterns are called out
• the next stage's biggest unknowns are explicit
• the route to the next skill is justified

Output Format

Keep the result short and structured.

Recommended sections:

• Relevant area
• Existing artifacts
• Prior learnings
• Local patterns
• Constraints
• Open questions
• Packet readiness
• Recommended next step

Hard Rules

• Do not invent repo structure that you did not verify
• Do not ignore missing git initialization when it materially affects tracked project work
• Do not skip prior docs if they clearly match the task
• Do not jump into implementation from this skill
• Do not collapse product, engineering, and operations observations into one unlabeled blob when the multi-lens pipeline is available
• Do not produce a packet that names paths but fails to explain why the next stage should care
• Do not treat cmon:understand as optional when the task is substantial and repo familiarity is low

Handoff

Record the handoff using:

• templates/workflow/stage-transition-decision-template.md

Typical transition decisions:

• proceed -> cmon:think

  • if the problem, direction, or scope is still open

• proceed -> cmon:design

  • if requirements are already clear but flow, state, or interface behavior still needs explicit design

• proceed -> cmon:plan

  • if the requirements and design are already clear enough

• proceed -> cmon:verify

  • if the task is to assess an existing implemented change against its approved plan and evidence

• revise -> cmon:understand

  • if the packet is directionally useful but still missing context the next stage would need

• block

  • if the repo area, task target, or prior-decision surface is still too ambiguous to route responsibly

Later stages should treat the context packet as the shared starting point rather than silently rebuilding incompatible context from scratch.