Live
Powered by

Nutrition intake skill refactor proposal

Objective

Refactor the nutrition intake workflow so the operational process lives primarily in dedicated skill files instead of being spread across AGENTS.md and other broad agent configuration files.

The target state is a cleaner system where:

  • AGENTS.md keeps only high-level role, ownership, and boundary rules
  • nutrition intake workflow details move into one or more dedicated skills
  • triggering becomes more explicit and easier to revise
  • the coordinator and specialists share a single canonical process definition instead of duplicated instructions
  • future changes to intake handling can be made in one place

Source inputs reviewed

  • AGENTS.md
  • intake/nutrition/README.md

Current problems

1. Too much nutrition workflow logic lives in AGENTS.md

AGENTS.md currently contains detailed operational instructions for:

  • copying nutrition media
  • creating daily logs
  • heading and timing conventions
  • routing-hand-off content
  • Edamam usage rules
  • staging ledger behavior
  • completion gates
  • delivery behavior for returned nutrition media

This makes AGENTS.md too large and mixes:

  • global coordinator doctrine
  • athlete communication boundaries
  • detailed nutrition intake execution steps

That is the wrong abstraction boundary.

2. Instructions are split across multiple layers

The current nutrition intake behavior is spread across:

  • AGENTS.md
  • intake/nutrition/README.md
  • the nutrition-reply skill
  • doctrine files
  • memory and user preference files

This increases drift risk. It also makes it harder to answer basic questions like:

  • which file is the source of truth for intake handling?
  • what applies to Coach Luca versus the nutrition specialist?
  • what is doctrine versus workflow versus reply formatting?

3. Workflow and communication rules are mixed together

The current system blends three different concerns:

  • intake persistence workflow
  • specialist routing and analysis workflow
  • athlete-facing reply formatting

These should be separated.

4. Revisions are expensive and error-prone

When the intake process changes, multiple files need updates. That increases the chance of stale instructions surviving in one place.

Refactor design goals

  1. Single canonical workflow definition for nutrition intake handling
  2. Progressive disclosure so only relevant detail loads when the task actually matches nutrition intake work
  3. Clear separation of concerns between doctrine, intake processing, and athlete reply generation
  4. Minimal AGENTS.md with durable role and safety rules only
  5. Explicit ownership boundaries between Coach Luca and nutrition
  6. Easy future maintenance when the intake process changes

Proposed skill structure

Create a new skill family centered on a two-skill architecture.

Primary proposal: split into two skills

skills/nutrition-intake/
├── SKILL.md
└── references/
    ├── workflow.md
    ├── persistence.md
    └── migration-map.md

skills/nutrition-analysis/
├── SKILL.md
└── references/
    ├── specialist-handoff.md
    └── data-contract.md

The reason to prefer two skills is that the current workflow actually contains two distinct jobs:

  • intake handling and persistence by Coach Luca
  • specialist-ready analysis and logging handoff for the nutrition agent

Separating those jobs produces cleaner triggers, smaller loaded instructions, and less mixing of coordinator work with specialist handoff detail.

Proposed skill responsibilities

nutrition-intake skill

This skill should govern intake handling from first receipt through durable persistence.

It should cover:

  • detecting that a message is a nutrition intake item
  • classifying single item versus photo batch versus follow-up context
  • copying media into the canonical workspace location
  • resolving consumed date versus received date
  • ensuring the canonical daily log exists
  • writing or updating the ## Nutrition section correctly
  • deciding when minimal staging or routing ledgers are still needed
  • defining completion gates
  • defining what must happen before specialist analysis or any athlete-facing reply is allowed

It should not own specialist handoff logic in detail, and it should not own the final athlete-facing nutrition response wording.

nutrition-analysis skill

This skill should govern the translation from persisted intake record to nutrition-specialist-ready analysis context.

It should cover:

  • building the nutrition-agent handoff context
  • defining required and optional handoff fields
  • setting meal role and session-context expectations
  • handling uncertainty states such as unknown ingredients or unverified gluten and dairy compatibility
  • defining the Edamam decision tree and evidence hierarchy
  • clarifying what belongs in routing context versus canonical daily-log interpretation

This skill should be the canonical source for specialist-facing intake analysis preparation.

Keep nutrition-reply focused on reply generation only

The existing nutrition-reply skill should remain the canonical source for:

  • athlete-facing nutrition reply wording
  • blocked language
  • message structure
  • delivery-ready response conventions

It should not be the source of truth for intake persistence or specialist handoff design.

Proposed doctrine split

What should remain in AGENTS.md

Keep only high-level durable rules such as:

  • Coach Luca is the coordinator
  • only Coach Luca communicates directly with the athlete
  • specialists do internal analysis, not direct athlete delivery
  • canonical files live inside the workspace
  • ownership boundaries across coordinator and specialists
  • attribution rules for outbound messages
  • high-level statement that nutrition intake handling is governed by the nutrition-intake skill
  • high-level statement that specialist-ready nutrition routing and analysis preparation are governed by the nutrition-analysis skill

What should move out of AGENTS.md

Move detailed nutrition intake execution rules into the new skills, including:

  • media copy requirements
  • daily log creation rules
  • ## Nutrition write requirements
  • heading format rules like ### HH:MM
  • timing interpretation rules for Received and Consumed
  • duplicate-minute suffix rules
  • routing-log content requirements
  • initial detected-item list requirements
  • gluten and dairy uncertainty handling
  • Edamam decision tree
  • completion gate rules
  • nutrition-photo return operational procedure, if it remains part of nutrition intake handling

What should remain in doctrine files

Keep doctrine files for cross-cutting structural rules such as:

  • section ownership in canonical daily logs
  • workspace containment boundaries
  • coordinator versus specialist authority
  • canonical storage paths

Doctrine should describe who owns what and what file is canonical, not the entire step-by-step workflow.

Proposed file roles after refactor

AGENTS.md

Purpose:

  • operating model
  • authority boundaries
  • coordination rules
  • short trigger statements pointing to the relevant skills

skills/nutrition-intake/SKILL.md

Purpose:

  • concise trigger description for intake and persistence work
  • workflow overview
  • instructions on when to read which reference file

skills/nutrition-intake/references/workflow.md

Purpose:

  • end-to-end intake workflow
  • branch logic for photo, text, follow-up timing, and batches
  • completion gate

skills/nutrition-intake/references/persistence.md

Purpose:

  • canonical paths for intake persistence
  • daily log creation behavior
  • heading standards
  • timestamp rules
  • media copy behavior

skills/nutrition-intake/references/migration-map.md

Purpose:

  • map old instruction locations to new ones
  • identify what can be removed from AGENTS.md
  • protect against duplicate live instructions during migration

skills/nutrition-analysis/SKILL.md

Purpose:

  • concise trigger description for specialist-routing and handoff preparation work
  • handoff overview
  • instructions on when to read which reference file

skills/nutrition-analysis/references/specialist-handoff.md

Purpose:

  • how Coach Luca builds specialist-ready routing context
  • evidence hierarchy
  • uncertainty handling
  • Edamam path selection rules

skills/nutrition-analysis/references/data-contract.md

Purpose:

  • required and optional handoff fields
  • meal-role, timing, and session-context expectations
  • routing payload standards

intake/nutrition/README.md

Recommended future role:

  • either deprecate it
  • or convert it into a thin note that points to the two skills and says the live process now lives there

It should not remain a competing source of truth.

Proposed skill trigger description

nutrition-intake trigger scope

The nutrition-intake skill description should trigger for intake-handling and persistence cases such as:

  • nutrition photos
  • meal photos
  • snack photos
  • supplement photos
  • food labels
  • athlete follow-up timing for a prior nutrition item
  • requests to log what was eaten or drunk
  • cases where the system needs to persist nutrition intake before any reply generation

It should trigger on work like:

  • “Sidney sent a meal photo”
  • “log this snack”
  • “this was actually yesterday’s dinner”
  • “save this into her daily nutrition log”

nutrition-analysis trigger scope

The nutrition-analysis skill description should trigger when the task is to prepare or standardize specialist-ready analysis context, for example:

  • analyze persisted nutrition intake
  • prepare the nutrition handoff
  • determine Edamam lookup path
  • structure routing context for nutrition review
  • classify uncertainty, meal role, or session relevance before nutrition interpretation

It should trigger on work like:

  • “analyze these nutrition photos”
  • “prepare the nutrition specialist handoff”
  • “what should the nutrition agent receive for this item?”
  • “build the routing context for this meal batch”

Proposed workflow model

Phase 1, intake detection

Coach Luca determines whether the inbound content is:

  • a new nutrition item
  • additional context for an existing unresolved item or batch
  • a return-media request
  • a summary request over existing logged intake

This phase is governed by nutrition-intake.

Phase 2, persistence

Before the item is considered handled:

  • copy media into athlete/logs/media/<date>/
  • resolve the effective date
  • ensure athlete/logs/daily/YYYY-MM-DD.md exists
  • write the canonical nutrition record into ## Nutrition

This phase is governed by nutrition-intake.

Phase 3, routing context

Build the handoff context needed by nutrition analysis, including:

  • detected foods
  • athlete-stated ingredients
  • timing context
  • meal role
  • session context
  • dietary safety uncertainty
  • whether Edamam image or named-food lookup path should be used

This phase is governed by nutrition-analysis.

Phase 4, specialist analysis

Nutrition specialist performs the analysis using the handoff context and writes the durable nutrition interpretation into the canonical log.

This phase is informed by nutrition-analysis.

Phase 5, athlete-facing reply

If a reply is required:

  • Coach Luca synthesizes the final message
  • nutrition-reply governs wording and structure
  • outbound attribution reflects actual contributors

Proposed handoff contract

The nutrition-analysis skill should define a stable internal contract between Coach Luca and nutrition.

Recommended fields:

  • athlete username
  • received timestamp
  • consumed timestamp or consumed window
  • effective entry date
  • source message grouping or batch identifier
  • media paths
  • detected items
  • athlete-stated items
  • meal role, provisional if needed
  • session timing relevance
  • dietary compatibility state, including uncertain
  • Edamam path used or pending
  • open assumptions requiring clarification

This contract can stay as Markdown-defined structure at first. It does not need a formal schema file yet unless automation expands.

Specific migration recommendations

Remove from AGENTS.md

Move the detailed blocks under:

  • Nutrition handling
  • Outbound nutrition media delivery, if that procedure is treated as part of nutrition intake operations rather than a general delivery rule

Keep only short replacement lines such as:

  • “Use the nutrition-intake skill for nutrition intake detection, persistence, and canonical logging work.”
  • “Use the nutrition-analysis skill for specialist-ready nutrition routing context and analysis preparation.”
  • “Use the nutrition-reply skill for athlete-facing nutrition response wording and blocked content.”

Replace intake/nutrition/README.md

Convert it into one of these:

Preferred

A short deprecation note:

  • this folder is no longer the live workflow definition
  • canonical intake workflow now lives in skills/nutrition-intake/ and skills/nutrition-analysis/
  • canonical athlete records live under athlete/

Alternative

Absorb its useful content into the skill references and reduce the README to a one-paragraph pointer.

Proposed implementation sequence

Stage 1, planning and draft

Create the proposal and agree on structure.

Stage 2, create the skills

Create:

  • skills/nutrition-intake/SKILL.md
  • skills/nutrition-intake/references/workflow.md
  • skills/nutrition-intake/references/persistence.md
  • skills/nutrition-intake/references/migration-map.md
  • skills/nutrition-analysis/SKILL.md
  • skills/nutrition-analysis/references/specialist-handoff.md
  • skills/nutrition-analysis/references/data-contract.md

Stage 3, migrate instructions

Move nutrition-intake operational detail out of:

  • AGENTS.md
  • intake/nutrition/README.md
  • any overlapping guidance files that duplicate the same workflow

Stage 4, tighten global files

Reduce AGENTS.md to short trigger statements and durable boundaries.

Stage 5, validate behavior

Test against representative cases:

  • single meal photo
  • multiple-photo batch
  • later timing correction
  • text-only meal log
  • label-only photo
  • request to resend a logged nutrition image
  • daily nutrition summary request

Risks and mitigations

Risk 1, skill does not trigger when needed

Mitigation:

  • make the skill description broad and concrete
  • include triggers for photos, text logs, timing corrections, and persistence requests

Risk 2, duplicate instructions remain live

Mitigation:

  • use migration-map.md
  • remove or sharply shorten the old sections after migration
  • avoid leaving two authoritative workflow definitions active

Risk 3, doctrine becomes too thin

Mitigation:

  • keep ownership, authority, and canonical-path rules in doctrine
  • move only operational procedure into the skill

Risk 4, skill overlap or fuzzy boundaries

Mitigation:

  • keep hard boundaries:
    • nutrition-intake owns intake detection, persistence, and canonical logging
    • nutrition-analysis owns specialist-ready routing context and evidence handling
    • nutrition-reply owns athlete-facing wording

Best practical architecture

  • AGENTS.md: coordination model, ownership, boundaries, brief trigger instructions
  • nutrition-intake skill: intake detection, persistence, and canonical logging workflow
  • nutrition-analysis skill: specialist-ready routing context, evidence hierarchy, and handoff contract
  • nutrition-reply skill: athlete-facing nutrition reply generation
  • doctrine files: file ownership, canonical paths, containment rules
  • daily logs: durable athlete records

This gives one clear place to edit each part of the workflow without forcing one oversized skill to carry the whole process.

Recommendation

Proceed with two new skills as the target architecture:

  • nutrition-intake
  • nutrition-analysis

Then:

  1. migrate intake detection, persistence, and canonical logging logic out of AGENTS.md into nutrition-intake
  2. migrate specialist-ready routing, evidence hierarchy, and handoff contract logic into nutrition-analysis
  3. convert intake/nutrition/README.md into a non-authoritative pointer or deprecation note
  4. keep nutrition-reply as a separate skill for athlete-facing output
  5. leave doctrine files responsible only for ownership, boundaries, and canonical storage structure

Proposed next action

After review of this proposal, the next implementation step should be:

  • create the nutrition-intake skill skeleton and draft its SKILL.md plus its three reference files
  • create the nutrition-analysis skill skeleton and draft its SKILL.md plus its two reference files
  • then revise AGENTS.md to replace detailed nutrition intake workflow blocks with short trigger-and-boundary statements pointing to the two skills