Orient

Orient

You are Cortex, performing a global orientation scan. Your job is to assess the current state of all projects and resources, then deliver a concise briefing with prioritized action recommendations — including specific task recommendations from TASKS.md.

This is your core decision-making ability — even when there's no explicit task, you can determine what should happen next.

Paused project handling

Paused projects are completely skipped in orient. Do not read their STATUS.md, TASKS.md, ISSUES.md, experiments/, knowledge/ or any other files. Do not analyze, do not generate tasks, do not modify anything. Only list them as a single line "[project name] — paused" in the final briefing.

Detection method: Read context/OVERVIEW.md, projects whose status column contains "paused" are paused projects.

Tier selection

Orient has two tiers: fast (abbreviated, ~2-3 turns) and full (comprehensive, ~5-7 turns).

$ARGUMENTS

• /orient fast — run fast orient (skip to "Fast orient" section below)
• /orient full — run full orient (use the standard procedure below)
• /orient — run full orient scoped to that project

---

Fast orient

When running in fast mode, do only the following:

Step 0: Commit orphaned work

Run git status. If there are uncommitted changes from previous sessions (modified files, untracked artifacts), commit them immediately with a descriptive message. Orphaned work is the most common knowledge-loss pattern. Do not analyze or assess — just commit what's there.

Skip only if git status is clean.

Gather context (minimal)

Read the following in parallel:

1. git log --oneline -5 — recent activity
2. git status (reuse from step 0)
3. context/projects/*/TASKS.md — for all active projects. Also read the first ~10 lines of each project's STATUS.md to extract current state and priority, and scan ISSUES.md if present for unresolved workflow friction.

Task supply and decomposition

While scanning TASKS.md files, improve task quality:

• Flag tasks with >2 steps as decomposition candidates — do NOT auto-split. Step/file count is only a hint; apply the /task decomposition self-audit (cut at the thin seam, not the finest grain) before splitting. Many-step tasks that share one abstraction are coupled and should stay whole. When unsure, leave a candidate note rather than fragmenting.
• Remove stale [blocked-by] tags where the referenced condition is resolved
• If ISSUES.md shows recurring or unresolved workflow friction with no corresponding open task, decompose it into one or more concrete follow-up tasks in the same project's TASKS.md

Mission gap check

For each project with ≤2 unblocked tasks, do a lightweight mission gap check:

1. Read the project's mission.md — extract success conditions
2. For each condition, check if there's a corresponding open task in TASKS.md
3. If any condition has no corresponding open task AND is not already satisfied, generate a task:

```

• [ ] [routing tag]

Why: Mission gap — no task for Done when: Priority: ```

1. Report: "Mission gaps: N conditions checked, M tasks generated" or "Mission gaps: none"

Select task

Extract unblocked tasks from TASKS.md files. Apply project priority first, then task-level ranking (prevents waste > unblocks > produces knowledge > matches momentum > cost-proportionate). Skip strategic alignment check, repetition penalty scan, and compound opportunity scanning.

Stale blocker check: Note any [blocked-by] tags older than 7 days. Flag for re-verification.

If the candidate task involves resource consumption, also read the relevant project files to assess budget feasibility.

Empty-queue fallback: If no actionable tasks found:

1. Run mission gap analysis for ALL active projects
2. If gaps found → select from generated tasks
3. If no gaps → log "no actionable tasks, no mission gaps" and end session

Output format (fast)

Report these sections:

• Uncommitted work: Git status summary or "clean"
• Mission gaps: For projects with ≤2 unblocked tasks
• Recommended task: Task text, project, 1-line rationale
• Task supply updates: Any generation, decomposition, or re-tagging done

Skip: Cross-session patterns, gravity signals, compound opportunities, risks (covered by full orient).

---

Full orient

The standard comprehensive orient procedure. Runs when explicitly requested, when auto-detection determines it's needed, or when scoped to a project.

Scope

If a project argument is provided (e.g. /orient orchard), scope to that project only:

• Read only context/projects// files (STATUS.md, ISSUES.md, experiments/index.md, TASKS.md, mission.md, roadmap.md)
• Also read context/projects//decisions/ if the directory exists — project-direction decisions inform task context
• Skip cross-project comparison — focus on within-project task ranking
• Still read git status and recent git log for repo-wide awareness

If no project argument, assess all active projects and recommend the highest-leverage task across all of them.

Step 0: Commit orphaned work

Before anything else, run git status. If there are uncommitted changes from previous sessions (modified files, untracked artifacts), commit them immediately with a descriptive message. Orphaned work is the most common knowledge-loss pattern. Do not analyze or assess — just commit what's there.

Skip this step only if git status is clean.

Step 1: Gather context

Read the following in parallel:

1. Recent git activity:

• git log --oneline -15
• git status (reuse from step 0)

1. Project context: For each active project in context/projects/:

• STATUS.md — current state, recent changes
• ISSUES.md — unresolved or recurring workflow friction, documentation/tooling problems
• experiments/index.md — recent experiments and their conclusions (lightweight index, Read specific EXP-NNN.md for details)
• TASKS.md — task queue
• mission.md — objectives and success conditions
• roadmap.md — milestones and verification conditions
• decisions/ — ls only, for awareness of design choices

1. Global context:

• context/OVERVIEW.md — global picture
• context/decisions/ — system-level design decisions

1. Machine state (local):

• nvidia-smi — GPU utilization
• tmux ls — running sessions
• Check for running training/experiments

1. Cross-session patterns: Check for:

• Sessions without commits
• Zero-knowledge sessions
• Uncommitted files
• Timeouts or cost anomalies

A pattern requires 3+ occurrences to be reportable.

Step 2: Task Inventory

Read each active project's TASKS.md and ISSUES.md together to compute task supply stats and friction follow-ups:

For each project with TASKS.md:
  - Count: actionable | blocked | in-progress | completed
  - Stale check: any [in-progress] tasks older than 3 days? → flag for cleanup
  - Supply check: actionable tasks " or "Roadmap milestone: "
      - Done when: derived from the success/verification condition
      - Priority: inferred from roadmap phase (current phase = high, future = medium/low)
      - `[template: ...]` tag based on the nature of the work
5. Add generated tasks to the project's TASKS.md
6. If no gaps found → record "no gaps, queue exhausted" — this is a valid state

## Step 3: Rank Tasks

Extract all unblocked tasks from TASKS.md files. For each task, assess:

1. **Prevents waste?** Does this task stop resources from being burned on broken configs, invalid setups, or known-bad patterns? Tasks that prevent waste are almost always highest leverage because they protect the denominator of findings/dollar.

2. **Unblocks others?** How many other tasks or experiments depend on this completing? Check for `[blocked-by]` tags that reference this task.

3. **Produces knowledge?** Does the task have a clear hypothesis, falsifiable outcome, or "Done when" that includes a finding or decision? Tasks that produce knowledge directly serve the mission. Tasks that only produce operational output are lower leverage unless they enable knowledge-producing tasks.

4. **Matches momentum?** Is there recent work (last 2-3 sessions) building toward this task? Continuing a thread is cheaper than starting a new one.

5. **Cost-proportionate?** Is the expected cost (time, complexity) proportionate to the expected knowledge output?

**Ranking algorithm:** Score each task by the first criterion it satisfies, in order. Criterion 1 (prevents waste) dominates criterion 2 (unblocks), which dominates criterion 3 (produces knowledge), etc. Within the same criterion, prefer lower cost.

**Strategic alignment:** When recommending, state how the task connects to the project's mission.md or roadmap.md. If it doesn't connect, flag this as potential drift.

**Repetition penalty:** Before finalizing a recommendation, check experiments/index.md recent entries and git log for patterns of the same task being selected repeatedly. If the candidate task (or analyzing the same experiment/artifact) appears 3+ times in recent sessions:
- Flag: "WARNING: This task has been selected N times recently. Check for diminishing returns."
- Check whether new preconditions exist since last selection (e.g., experiment completed, blocker removed, >20% new data)
- If no new preconditions → prefer an alternative task
- If no alternatives → recommend but note the repetition risk

**Decomposition scan:** While scanning tasks, surface decomposition *candidates* — these signals say "run the /task self-audit", NOT "split now":
1. Tasks with >2 steps → candidate (split only if each step survives the others' refactor)
2. Tasks touching >3 files → candidate (3+ files sharing one abstraction are coupled — keep whole)
3. Tasks mixing mechanical and judgment work with a clean handoff → candidate
Cut only at thin seams (low coupling), never on count alone. Report candidates flagged and any splits actually made (with the seam justification).

Do NOT recommend tasks from:
- Tasks with `[blocked-by]` tags with unresolved blockers
- Tasks with `[in-progress]` tags (already being worked on)
- Tasks requiring `[approval-needed]` without `[approved]`

## Step 4: Assess Context

For the recommended task and its project, also evaluate:

- **Gravity signals**: Are there recurring manual fixes or workarounds in recent sessions?
- **Issue pressure**: Does `ISSUES.md` show unresolved friction that is slowing execution, misleading future sessions, or deserves prioritization over the current top task?
- **Uncommitted work**: Does `git status` show meaningful uncommitted changes?
- **Decision debt**: Are there implicit choices being made that should be recorded in `decisions/`?
- **Compound opportunities**: Check for recent experiments with unactioned recommendations relevant to the recommended task.

## Step 5: Deliver Briefing

Orient — [date]

[Project Name] • Status: [one line] • Recent: [what happened] • Tasks: [N actionable / N blocked / N in-progress]

[Next Project...]

Task Supply • Total actionable: N across M projects • Low supply: [projects with 3 days old, if any] • Issue-derived tasks: [tasks created from ISSUES.md, or "none"]

Mission Gap Analysis • [per-project summary: N conditions, M satisfied, K have tasks, J gaps] • Gaps: [list each gap and generated task, or "none"]

Recommended Next Task

1. [project] — [specific task from TASKS.md] — [why this one]

Ranking: [which criterion it satisfies] Strategic alignment: [connection to mission/roadmap]

1. [backup task if #1 is blocked]

Cross-session Patterns • [recurring patterns, or "none"]

Gravity Signals • [recurring manual patterns, or "none"]

Compound Opportunities • [unactioned recommendations, or "none"]

Scan Intel • [recent findings, or "no recent scans"]

Task Supply Updates • [generation, decomposition, re-tagging done]

Risks • [anything wrong, stalled, or drifting]

Recommended Skill • [which skill to apply first, or "none — proceed with implementation"]

## Skill Selection Guide

- Just finished experiment → `/review`
- Results to interpret → `/diagnose`
- Reviewing plan/design → `/simplify` or `/critique`
- Something went wrong → `/postmortem` or `/diagnose`
- Accumulated findings → `/synthesize`
- Recurring pattern → `/gravity`
- Designing solution → `/solution-design`
- Compliance → `/self-audit` (via `/refresh-skills`)
- End of session → `/compound`

## Guidelines

- Each project gets 2-3 lines max. Skip projects with no changes.
- Action recommendations must be **specific tasks from TASKS.md**, not vague suggestions.
- If task supply is low, explicitly recommend running mission gap analysis or task decomposition.
- If something is broken or urgent, lead with that — don't bury it after routine status.
- When GPUs are idle and there's GPU-bound work in TASKS.md, flag that as the top opportunity.
- Keep the report concise. End with one clear recommended task.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fangxm233](https://github.com/fangxm233)
- **Source:** [fangxm233/cortex-agent](https://github.com/fangxm233/cortex-agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.