# Template Improvement Directives # Generated: [AI_DATE_GENERATION_PROHIBITED] # Source Project: ITPR (Reset) directives: - directive_id: "TID001" target_template_id: "ProjectStateSchema.yaml" # And by implication, all templates using/generating dates target_section_or_field: "All date/timestamp fields (e.g., metadata.last_modified_timestamp, charter.date_formalized, logs.timestamp, execution.tasks.start_timestamp, etc.)" issue_description: "Current use of '[AI_DATE_GENERATION_PROHIBITED]' placeholder for AI-unsourceable dates is problematic, conspicuous, and clutters outputs. AI should not invent dates." proposed_change_type: "ModifyFieldSchemaAndGuidance" proposed_change_details: | 1. Review all date/timestamp fields in ProjectStateSchema. 2. Make fields optional wherever feasible if they are not critical for process logic or user-provided. 3. For fields that *must* exist per schema but AI cannot populate: - Option A: Allow them to be truly empty/null if the schema validator permits. - Option B: Introduce a standard, less obtrusive way to indicate "AI Cannot Source" (e.g., a specific keyword like `UNSOURCEABLE_AI_TIMESTAMP` or a related boolean field `is_timestamp_ai_generated: false`). 4. Update all process templates (00-05) to instruct AI on how to handle these fields according to the revised schema guidance (e.g., "Omit if optional and unsourceable," or "Use designated null/unsourceable marker"). rationale: "Improves clarity, reduces clutter, adheres to 'AI does not invent dates' principle. (Ref: INS001)" source_insight_refs: ["INS001"] status: "Proposed" - directive_id: "TID002" target_template_id: "All Process Templates (00-Explore.md to 05-Close.md)" target_section_or_field: "Instructions related to file saving, naming, and directory structure." issue_description: "Current practices or lack of clear instruction lead to inconsistencies or overly complex file management (e.g., versions in filenames, nested directories)." proposed_change_type: "UpdateInstruction" proposed_change_details: | 1. Standardize instructions for saving project artifacts (Charters, Plans, State files, KAs, Deliverables): - Filenames should NOT include version numbers (e.g., `[ProjectCode]_Plan`, not `[ProjectCode]_Plan_vX.Y`). Internal `version` field in YAML tracks this. - Default save location should be the main project directory (e.g., `projects/[ProjectCode]/`) unless a specific, simple subdirectory (e.g., `outputs/` for final human-readable deliverables) is explicitly agreed upon and consistently used. Avoid deep nesting. 2. State files should use sequential numbering (e.g., `[ProjectCode]_State_001`). rationale: "Simplifies file management, aligns with user preference, leverages external version control. (Ref: INS_FilenameNoVersion, INS001)" source_insight_refs: ["INS_FilenameNoVersion", "INS001"] status: "Proposed" - directive_id: "TID003" target_template_id: "All Process Templates, AISkillsCatalog.yaml (for AI persona definition), ITPR_StyleGuide (as a model)" target_section_or_field: "AI communication style, instructional text within templates, AI self-critique guidelines." issue_description: "AI responses sometimes include conversational filler, hedging, or inappropriate evaluative language, deviating from the desired direct, assertive, matter-of-fact machine voice." proposed_change_type: "UpdateGuidanceAndInternalProtocol" proposed_change_details: | 1. All instructional text within process templates written for the AI should model direct, concise language. 2. AI operational protocols (potentially part of AISkillsCatalog or a new AI Persona Definition KA) should mandate: - Avoidance of conversational filler, apologies, personal opinions (Ref: INS007 - "Don't say it, do it!"). - Avoidance of superfluous laudatory/emotive adjectives (e.g., "profound," "remarkable") when describing concepts. Significance should be shown, not asserted adjectivally. (Ref: User feedback on D001 drafts). - Strict protocol for identifying and flagging/clarifying any hedging or "waffle words" on core assertions with the user *before* inclusion in formal drafts. (Ref: INS010). 3. `Meta-RefineOutput.md` could be updated to include checks for these stylistic elements during AI self-critique. rationale: "Ensures consistent AI persona, improves clarity and impact of AI outputs, aligns with user's stylistic preferences. (Ref: INS004, INS007, INS010, specific draft feedback)" source_insight_refs: ["INS004", "INS007", "INS010"] status: "Proposed" - directive_id: "TID004" target_template_id: "05-Close.md, ProjectStateSchema.yaml (KA structure)" target_section_or_field: "KA handling, project archival." issue_description: "Knowledge Artifacts (Glossary, Primer, Style Guide) have value as standalone documents beyond the project, but current process primarily embeds them in Project State YAML." proposed_change_type: "AddNewFeatureOrGuidance" proposed_change_details: | 1. `05-Close.md` (Project Closing) should include a step to prompt the user if they wish to export key KAs as separate, formatted standalone documents (e.g., Markdown, PDF). 2. AI should have a skill or process for formatting and outputting these KAs cleanly. 3. Consider if `ProjectStateSchema.yaml` needs a field in KA objects to store a "standalone formatted version" or a path to it, if generated. rationale: "Enhances reusability and value of generated KAs. (Ref: INS_KAReusability)" source_insight_refs: ["INS_KAReusability"] status: "Proposed" - directive_id: "TID005" target_template_id: "04-Monitor.md, 05-Close.md, ProjectStateSchema.yaml (new schema for feedback)" target_section_or_field: "Process improvement feedback loop." issue_description: "Current method of logging insights for template improvement is ad-hoc. A structured, machine-readable format is needed for systematic template evolution." proposed_change_type: "DefineNewSchemaAndIntegrate" proposed_change_details: | 1. Develop a `TemplateFeedbackSchema.yaml` (as discussed, with fields like `feedback_item_id`, `target_template_id`, `target_section_or_field`, `issue_description`, `proposed_change_type`, `proposed_change_details`, `rationale`, `status`). 2. `04-Monitor.md` should include a step to review logged insights and translate relevant ones into instances of this `TemplateFeedbackSchema`. 3. `05-Close.md` should include a step to consolidate all `TemplateFeedbackSchema` instances from the project as a key output for the "ProcessMaintainer/AI." 4. `ProjectStateSchema.yaml` should include a section to store these structured feedback items (e.g., `metadata.template_improvement_directives: list_of_TemplateFeedbackSchema_instances`). rationale: "Enables systematic, traceable, and potentially automatable continuous improvement of all project templates and processes. (Ref: INS005)" source_insight_refs: ["INS005"] status: "Proposed" - directive_id: "TID006" target_template_id: "All Process Templates (especially transition points like end of 01-Initiate, 02-Plan, 04-Monitor)" target_section_or_field: "Logic for transitioning to next process template / requesting templates." issue_description: "AI sometimes incorrectly requests templates already loaded or fails to state when a template is missing." proposed_change_type: "UpdateProceduralLogic" proposed_change_details: | At any point where a transition to a new process template is indicated: 1. AI must first check its active context if the required template (and version, if specified) is already loaded. 2. If loaded, AI states: "Proceeding with loaded [template_name] vX.Y." 3. If not loaded, AI states: "I do not have [template_name] vX.Y in my current context. Please provide it to proceed." rationale: "Improves AI operational efficiency, reduces redundant user actions, ensures correct template usage. (Ref: INS006)" source_insight_refs: ["INS006"] status: "Proposed" - directive_id: "TID007" target_template_id: "03-Execute.md, InvokeAISkill.md (or similar skill execution template)" target_section_or_field: "Handling and presentation of large text deliverables." issue_description: "AI has repeatedly failed to output large text deliverables (e.g., full drafts) completely and directly for user review, causing critical process blocks." proposed_change_type: "UpdateProceduralLogicAndOutputStrategy" proposed_change_details: | 1. When an AI skill or process step in `03-Execute.md` generates a large text deliverable intended for immediate user review: - AI must explicitly state its strategy for outputting this large text (e.g., "This will be a long output. I will provide it chapter by chapter."). - AI must output the text in clearly labeled, sequential parts. - AI must await user acknowledgement (e.g., "continue," "next") after each part before sending the next. - AI must confirm when the entire output is complete. 2. The primary review should occur on this directly provided text, not by requiring the user to extract it from a state file. The state file serves as the archive *after* review or alongside it. 3. `InvokeAISkill.md` (if it handles output presentation) or the relevant steps in `03-Execute.md` must incorporate this logic. rationale: "Ensures user receives and can review critical deliverables effectively, preventing project stalls and improving trust in AI output. (Ref: INS009, ISS001_RepeatFailure_OutputTruncation)" source_insight_refs: ["INS009"] status: "Proposed" - directive_id: "TID008" # New, based on our very recent discussion target_template_id: "00-Explore.md, 02-Plan.md" target_section_or_field: "Project Scoping, Argument Structure Development, WBS generation." issue_description: "Complex, foundational projects may require iterative refinement of core concepts and argument structure *before* a stable plan or full draft can be developed, sometimes necessitating a 'reset' or loop back to exploration/initiation." proposed_change_type: "AddGuidanceAndProcessFlexibility" proposed_change_details: | 1. `00-Explore.md` and `01-Initiate.md` should acknowledge that for highly novel or complex conceptual projects, the initial exploration might lead to a plan that later proves insufficient, requiring a "Phase 0 Reset" where the accumulated learning becomes input for a *new* exploration and initiation cycle (as occurred in ITPR). Templates should allow for this iterative deepening. 2. `02-Plan.md` should emphasize that the WBS for such projects, especially for deliverables like D001 (monograph), might need to be very high-level initially, with detailed task breakdown for early conceptual chapters/parts, and later parts remaining more flexible until core concepts are solidified. 3. The concept of "Guiding Paradoxes/Spectra" and "Argumentative Pillars" as outputs of `00-Explore.md` should be considered for inclusion as structured fields in `project_state.exploration_history` to better capture foundational strategic decisions. rationale: "Better accommodates the iterative and sometimes recursive nature of deep conceptual work and foundational theory development. Formalizes successful ad-hoc process adjustments made in ITPR. (Ref: ITPR project reset experience)" source_insight_refs: ["ITPR Project Reset Event"] status: "Proposed"