Task Formulation
Purpose
Transforms a raw user request (e.g., "add authorization") into a formulated task — a structured document containing
the description, technology stack, dependencies, and scope estimate. The output is persisted at the path printed by
goga history path -f task.md (run goga history ensure first if the topic directory does not exist)
and serves as input for the goga-prototype skill.
When the request decomposes into several subtasks, the main task (the first subtask) is persisted as described above;
each additional subtask becomes a separate topic via goga topics create <branch-name> --todo with its full task
document piped via stdin.
Dialogue Rules
Drive the conversation through hypotheses. Present concrete options rather than open-ended questions.
Ask one question per message. Deliver a single focused question with 2-4 answer options.
Structure every response. This discipline prevents unstructured discussion.
Phase 1: Input Collection
Accept the user's description of the desired outcome.
The description may be:
- Brief — a single sentence or feature name
- Detailed — a complete specification with requirements
If the description is brief, do not request clarifications yet. Phase 3 will resolve missing details. Retain the original description throughout the session.
Phase 2: Context Loading
Step 1: Load the DSL specification
Invoke goga-cell via the Skill tool.
Purpose:
- Understand cell and CODEMANIFEST terminology for analyzing the existing architecture
Step 2: Load DSL application principles
Invoke goga-cookbook via the Skill tool.
Purpose:
- Understand the two-level usages model (project-level
.goga/usages/and cell-level<cell_path>/.usages/) - Learn usage file authoring principles for creating
.goga/usages/cooks/
Step 3: Retrieve the project schema
Run goga schema to obtain the cell hierarchy.
If the project lacks an existing architecture, record this as a known fact.
Step 4: Retrieve base annotations and usages
Invoke goga-codemanifest-base via the Skill tool.
Step 5: Read relevant usages
If the task involves external libraries or technologies:
- Run
goga usages sync— materializes missing dependency usages; existing ones are not touched - Run
goga usages status— the source of truth for dependency usage state (a non-zero exit means drift, not a failure) - Read the relevant usages — hand-authored in
.goga/usages/cooks/, synced read-only in.goga/usages/<group>/<dep>/ - If a dep is
out of date, rungoga usages status --info:- Changed files irrelevant to the task — proceed with the local state
- Changed files relevant to the task — ask the user: refresh the dep via
goga usages -g <group> -d <dep> sync --forceor continue with the local state
Phase 3: Task Formulation
Objective: Align with the user on the exact scope and boundaries of the task.
Using the user's description (Phase 1) and project context (Phase 2), iteratively formulate the task:
Define the current state — based on Phase 2 context, describe:
- For new features — what the project currently lacks
- For modifications — how the affected area currently operates and what is unsatisfactory
Propose a hypothesis — a concrete task formulation with defined boundaries:
- What to implement
- What is explicitly out of scope
- Which existing cells are impacted
Ask a single question — validate whether the current state description and hypothesis are correct, and whether any aspects are missing
Await the response — adjust and repeat
After formulation approval — offer to include code examples in the task:
- If the task describes a library or API — suggest defining the target API with usage examples in the project's language
- If the user emphasized a specific API or code during discussion — suggest capturing it in the task
- If the user wants to write code directly — accept and include it in the task
- If examples are unnecessary — proceed to Phase 4
Completion criteria:
- The task essence is formulated unambiguously
- Scope boundaries are defined (included and excluded)
- The user has approved the formulation
Phase 4: Technology Stack and External Dependencies
Objective: Define the technology stack and identify external dependencies.
Define the implementation stack — technologies to be used:
- Frameworks, libraries, databases, message brokers, infrastructure components
- Existing project usages (in
.goga/usages/) that already describe the tools in use
Identify external dependencies — components not yet present in the project:
- If the task requires a new component, record it
- For each external dependency, check whether a usage file exists in
.goga/usages/cooks/or in a synced dependency directory.goga/usages/<group>/<dep>/ - Synced dependency usages are read-only — reference them, never schedule creation or update
- If no usage file exists, schedule creation in Phase 5
- If an existing usage file does not cover new usage patterns, schedule an update in Phase 5
Await feedback — the user approves or requests changes
- Approved → proceed to Phase 5
- Rejected → propose a revised stack incorporating the feedback
Completion criteria:
- Implementation stack is defined (frameworks, libraries, databases, brokers, infrastructure)
- External dependencies are documented
- Usage files to create or update in
.goga/usages/cooks/are identified; relevant synced usages are listed as read-only references
Phase 5: Usage File Management (.goga/usages/cooks)
Objective: Ensure all external dependencies from Phase 4 are covered by usage files.
Synced dependency usages (.goga/usages/<group>/<dep>/) are read-only — they enter the External Dependencies table with status existing (synced) and are never created or updated here.
For usage file authoring principles, invoke the goga-cookbook skill.
Creating new usage files
For each external dependency without a usage file:
Propose usage file content:
- Component description and purpose
- Usage patterns relevant to the current task
- Code examples
Await feedback — the user approves or requests changes
- Approved → create
.goga/usages/cooks/<name>.md - Rejected → propose revised content
- Approved → create
Updating existing usage files
For each dependency whose usage file does not cover new usage patterns:
Propose additions — sections and examples to add to the existing file
Await feedback — the user approves or requests changes
- Approved → update
.goga/usages/cooks/<name>.md - Rejected → propose revised additions
- Approved → update
If all external dependencies are covered by current usage files, skip this phase.
Phase 6: Scope Estimation
Objective: Assess the task scale and determine whether decomposition is necessary.
Assess the scale:
- Number of entities/types involved
- Presence of multiple independent subsystems
- Complexity of interactions
Present the estimate to the user:
- Single task or multiple tasks
- If multiple, propose a breakdown into subtasks
- Each subtask must deliver independent value
- The first subtask is the main task — it stays on the current branch's topic and is persisted in Phase 7 as the task document
Await feedback — the user approves or requests changes
Confirm branch names (decomposition only): propose a kebab-case branch name for each additional subtask as one list; the user confirms or edits the names in a single reply. Await approval before Phase 7.
Phase 7: Task Persistence
Objective: Create the additional subtask topics, then save the main task document via goga history path -f task.md (goga history ensure first if the topic directory does not exist).
The topic directory is the current one in the history tree, resolved by goga history path.
Read the
task-template.mdtemplate from the current skill directory.Create the additional topics (decomposition only), one per additional subtask, each with a full task document:
cat <<'EOF' | goga topics create <branch-name> --todo <full task document> EOF- Quoted
'EOF'— backticks and$pass verbatim; the document must not contain a bareEOFline - No
--switch, no--publish— you stay on your branch - Capture each
Created branch <branch> and topic <year>/<slug>line — the main document references these values - Create all topics before writing the main document
- Quoted
Save the main task document at the path from
goga history path -f task.md. Its Scope Estimate lists every created topic: branch name +<year>/<slug>.Present a summary to the user:
- Task name
- Technology stack
- External dependency count
- Scope (single task / decomposition — for a decomposition, the created topics with branch names)
- Risks and constraints
Failure handling:
- Occupied name or slug — ask a new branch name for that subtask only and retry; never touch created topics.
- Missing base ref — the clean error names the options (
--base-ref,--from-current,topics.base_refin.goga/config.yml); ask the user and retry. - Todo input — use the exact heredoc form: the value-less
--todois required with a pipe;--todo "<text>"ignores the pipe.