takt-optimizer

TAKT Optimizer

Execute optimization of existing TAKT workflows. Diagnosis and analysis are handled by takt-analyze.

Prerequisite takt version: v0.47.0

Reference materials

Material	Path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Validation criteria for workflow structure
Engine specification	references/takt/builtins/skill/references/engine.md	Understanding of prompt construction and token consumption
Style guide group	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet size limits
Built-in workflow	references/takt/builtins/ja/workflows/	Reference for optimization patterns
Built-in facet	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	Built-in replacement candidates

Differences from takt-analyze

Perspective	takt-analyze	takt-optimize
Purpose	Problem detection, diagnosis, and reporting	Execution of optimization
Output	Analysis report (Markdown)	Optimized file group
Changes	None (read-only)	Directly edit and generate files
Input	Workflow YAML + facets + execution log	Workflow YAML + facet + takt-analyze diagnostic results
Judgment	Severity classification of problems	Cost/quality trade-off judgment
Log analysis	Execute it itself and generate a diagnostic report	Utilize takt-analyze diagnostic results

Recommended flow: takt-analyze(Diagnosis) → based on the results, takt-optimize(optimization execution)

Optimization categories

1. Token consumption reduction

Reduce the amount of tokens during prompt construction.

Engine prompt construction order (see: engine.md):

ペルソナ → ポリシー → コンテキスト → ナレッジ → インストラクション
→ タスク → 前回出力 → レポート指示 → タグ指示 → ポリシーリマインダー

Note: Policies are injected twice, at the beginning and at the end (as a countermeasure against Lost in the Middle). Policy bloat doubles token consumption.

Optimization	Method	Effect
Persona compression	Removal of redundant descriptions, compression within size limits	Reduction at each step
Policy splitting	Split huge policies by purpose and assign them only to the necessary steps	Double effect (for the reminder portion)
Knowledge narrowing	Remove knowledge references unnecessary for the step	Reduction of unnecessary context
Instruction simplification	Remove manual descriptions of content that is automatically injected	Deduplication
Output contract slimming	Compress output contracts over 30 lines	Reduce in report instruction sections

Facet size guideline:

Facet	Recommended	Upper limit
Persona (simple)	30-50 lines	100 lines
Persona (expert)	50-300 lines	550 lines
Policy	60-250 lines	300 lines
Instruction (review)	5-12 lines	-
Instruction (plan/fix)	10-20 lines	-
Instruction (implement)	30-50 lines	-
Output Contract	10-25 lines	30 lines

2. Step consolidation

Consolidate unnecessary steps to reduce the total number of steps in the workflow.

Pattern	Detection condition	Optimization
Consecutive identical personas	Adjacent steps have the same persona	Consolidate into 1 step
Single rule transition	A single rule with an unconditional transition	Consider consolidation with preceding and following steps
edit=false chain	Chain of read-only steps	Evaluate consolidation potential

Consolidation criteria:

• Whether personas are the same or different between steps
• Whether the session: refresh boundary is preserved
• Whether independence of report output is required
• Whether rule branching is substantively meaningful

3. Rule simplification

Streamline rule conditions.

Optimization	Before	After
ai() → tag replacement	ai("実装が完了した")	"実装完了" (tag-based)
Remove unreachable rules	One of the three conditions is unreachable	Delete unreachable rules
Shorten condition text	"全てのレビュアーが承認した"	"approved"

ai() vs tag-based decision:

• Tag-based (recommended): when results can be clearly classified
• ai(): only when context understanding is required for the judgment

4. Facet reuse

Replace custom facets with built-ins to reduce the section map.

Procedure:

1. List custom facets in the section map
2. Read the contents of each custom facet
3. Compare with built-in facets and evaluate similarity
4. If replaceable, replace with a bare name reference

Built-in replacement example:

# Before: カスタムファセットをセクションマップで参照
personas:
  my-coder: ../personas/my-coder.md
steps:
  - name: implement
    persona: my-coder

# After: ビルトインのbare name参照
steps:
  - name: implement
    persona: coder    # ビルトインを直接参照

Conditions under which replacement is not possible:

• Personas containing domain knowledge not found in built-ins
• Policies containing project-specific judgment criteria
• Instructions containing proprietary procedures

5. Loop control improvement

Improve the efficiency and safety of the fix loop.

Optimization	Details
Add loop_monitors	Add when there is no loop_monitor in the review→fix cycle
Adjust threshold	Suggest an appropriate value when the threshold is too high/too low
Add ABORT condition	Add when there is no ABORT transition on failure
max_steps adjustment	Adjust when max_steps is too large/too small relative to the number of steps
Fix supervise failure transitions	supervise On failure, plan the rule that transitions to fix is changed tosupervise → plan loops tend to be costly and unproductive
Add prohibition of builds with edit=false	edit: false Add a prohibition section (## やらないこと) stating "do not execute build commands" to the instructions referenced by the step of
Normalize instructions for loop monitor judge	loop_monitors.judge.instruction Unifyloop-monitor-ai-antipattern-fix, loop-monitor-reviewers-fix), and remove the old judge template notation
Migrate allowed_tools to provider_options	Top-level allowed_tools を provider_options.claude.allowed_tools (v0.30.0 and later)
Organize command quality gate	Separate the string gate and the type: command gate, and limit the command gate to agent steps. Remove unnecessary command gates, and if necessary, check the permission settings on the config side
provider_options.$ref → extends migration	In the workflow, provider_options.$ref: provider-options/edit.yaml を provider_options.extends: edit rewrite to (v0.47.0 and later BREAKING: old $ref is invalid)
persona_providers → provider_routing migration	In the workflow, persona_providers: delete and migrate to the project/global setting provider_routing.personas(or provider_routing.tags/provider_routing.steps) (deprecated since v0.47.0)

threshold recommended values:

• review→fix cycle: 3 times
• supervise→fix cycle: 3 times
• implement→test cycle: 2 times

6. Parallelization proposal

Detect steps that are executed sequentially but can be parallelized.

Parallelization conditions:

• Do not reference each other's output (pass_previous_response not needed)
• Take the report of the same previous step as input
• Output independent reports

# Before: 逐次レビュー
- name: arch-review
  ...
  rules:
    - condition: done
      next: qa-review
- name: qa-review
  ...

# After: 並列レビュー
- name: reviewers
  parallel:
    - name: arch-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
    - name: qa-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
  rules:
    - condition: all("approved")
      next: supervise
    - condition: any("needs_fix")
      next: fix

7. Optimization based on log diagnosis results

Using the log diagnosis results of takt-analyze as input, execute optimization based on actual data.

Premise: Reading, analyzing, and diagnosing logs is handled by takt-analyze. In this category, only "what to change" is handled based on the diagnosis results.

Available log sources:

Log file	Granularity	Purpose
logs/<session>.jsonl	Step unit	Loop detection, rule evaluation efficiency, ABORT rate
logs/<session>-provider-events.jsonl	Provider call unit	Token consumption of each call
logs/<session>-usage-events.phase.jsonl	Phase unit (v0.45.0 and later)	Token consumption of step × phase × provider.observability.usage_events_phase: true Output withnpm run analyze:usage Can be aggregated with
OTLP span / metric（v0.46.0〜）	Span / metric unit	OTEL_EXPORTER_OTLP_ENDPOINT Sent to Grafana Tempo etc. at configuration time. Because provider spans are nested in the workflow trace, the correspondence between steps and provider calls can be checked in the trace view

Diagnosis results → Optimization actions:

takt-analyze diagnosis	Optimization action
Loop hotspot (Warning/Critical)	loop_monitor の threshold adjustment, review of rule conditions
Dead rule (Critical)	Removal of unreachable rules
Rule evaluation efficiency is low (ai_judge_fallback high frequency)	Rewrite to tag-based rules, add tag output instructions to output-contract
ABORT rate is high	Flow improvement according to the reason of the ABORT cause (max_steps adjustment, addition of ABORT conditions)
Repeated errors by phase	Improvement of instructions and personas for phases with frequent errors
Iteration efficiency is low	max_steps Calculation of appropriate values for, consideration of step integration

Workflow

Step 1: Identifying and loading the target

Identify the target workflow YAML and load all related facets.

探索順序:
1. ユーザー指定のパス
2. ~/.takt/workflows/ 内のカスタムワークフロー
3. .takt/workflows/ 内のプロジェクトワークフロー

What to load:

• The entire workflow YAML
• All facet files of the section map
• Built-in facets (for comparison)
• takt-analyze diagnosis report (if provided)

Step 2: Creating an optimization plan

Evaluate the optimization potential of each category and present a plan.

# 最適化プラン: {ワークフロー名}

## 分析ソース
- 静的分析: ワークフローYAML + ファセット{N}件
- takt-analyze診断: {診断レポートの要約}（提供された場合）

## 推定効果
- トークン削減: 約{N}%
- ステップ数: {before} → {after}
- ファイル数: {before} → {after}

## 最適化項目
| # | カテゴリ | 対象 | 内容 | 根拠 | リスク |
|---|---------|------|------|------|--------|
| 1 | トークン削減 | persona/coder | 120行→80行に圧縮 | 静的 | 低 |
| 2 | ビルトイン置換 | persona/my-reviewer | → architecture-reviewer | 静的 | 低 |
| 3 | ルール簡素化 | ai_review | ai_fallback 67% → タグ化 | 診断 | 低 |
| 4 | 並列化 | arch-review + qa-review | 逐次→並列 | 静的 | 中 |

Confirm with the user: Present the plan and obtain approval for the items to execute.

Decision flow:

• 0 optimization items → report "Already sufficiently optimized" and end
• User approves some → execute only the approved items in Step 3
• User rejects all → end

Step 3: Executing optimization

Execute the approved items.

Execution order (in dependency order):

1. Facet compression/integration (changes to file contents)
2. Built-in replacement (changes to the section map)
3. Step integration (changes to the YAML structure)
4. Rule simplification (changes to rule conditions)
5. Loop control improvement (adding loop_monitors)
6. Parallelization (major changes to the step structure)

Step 4: Consistency verification

Check the consistency of the file group after optimization.

• The section map keys and in-step references match
• The section map paths point to files that actually exist
• initial_stepがstepsexists in the array
• All rules'nextare valid transition destinations
• parallel parent rulesall()/any()use
• to the rule of the parallel substepnextis missing
• Facets are within the size limit
• No references to deleted facets remain

Step 5: Result report

# 最適化結果: {ワークフロー名}

## サマリー
- トークン削減: 約{N}%（推定）
- ステップ数: {before} → {after}
- ファイル数: {before} → {after}

## 変更一覧
| # | ファイル | 変更内容 |
|---|---------|---------|
| 1 | workflows/my-workflow.yaml | ステップ統合、ルール簡素化 |
| 2 | personas/coder.md | 120行→80行に圧縮 |
| 3 | (削除) personas/my-reviewer.md | ビルトインに置換 |

## 削除ファイル
- personas/my-reviewer.md（→ ビルトイン architecture-reviewer で代替）

## 注意事項
{最適化による動作変更の可能性がある場合に記載}

Validation

Created/edited files can be mechanically verified with validate-takt-files.sh :

bash .agents/skills/takt-optimize/scripts/validate-takt-files.sh

Verification items:

• Workflow YAML: Required fields (name/initial_step/steps）、initial_step step references, existence of facet file references
• Facet .md: Empty check, persona/policy/knowledge require # 見出し , instruction/output-contract require content presence

Option --workflows / --facets can be used to narrow down the targets.