Tiinex Feedback

feedback is the experimental home for topic-oriented feedback tooling and artifacts.

Contribution guide:

• CONTRIBUTING.md

Current Status

As of May 2026, this repo contains existing topic artifacts under topics/ and now includes its first buildable VS Code extension scaffold under ides/vscode.

The current VS Code package is intentionally small and truthful:

• it is a real extension package that builds, tests, links into the main host, and packages to VSIX
• it now declares a top-level extension icon and current marketplace-facing manifest surface
• it is experimental
• it is focused on topic-oriented feedback reading surfaces first
• it does not claim that the full topic creation and editing workflow is finished yet

The first real reading slice is now present:

• a bounded topic index surface over topics/
• direct opening of the latest topic file
• direct reveal of the topics/ folder
• a separate feedback LM tool namespace is now present through get_feedback_topic_index
• the marketplace-facing VS Code package lives under ides/vscode as Tiinex Feedback
• feedback-specific settings now live under tiinex.feedback.*

Repo Layout Rule

This repo does not have vscode in its name, so IDE-specific implementation belongs under ides/<ide>.

Current layout:

• root: repo docs, license, notice, and topic artifacts
• ides/vscode: the VS Code extension package for experimental feedback tooling

Boundary

This repo is the intended home for experimental topic-oriented feedback tooling, especially topic creation and topic reading surfaces.

This is intentionally separate from:

• ai-provenance, which holds provenance-first tooling
• ai-vscode-tools, which still carries broader VS Code host-specific and experimental AI workflow tooling

Current operating posture:

• keep the VS Code package in ides/vscode buildable, linkable, and truthful about the current surface
• add bounded topic-reading and topic-creation surfaces incrementally rather than claiming a finished workflow too early
• keep claims experimental until the actual feedback workflow is proven end to end

Next Milestone Notes

• prefer a smaller number of stronger topic tools over a large family of narrow one-action tools
• treat topic interaction as a bounded surface design problem: one good read/index surface, one good focused topic view, and a small mutation surface should beat a sprawl of command-shaped tools
• reuse the provenance lesson: keep the core contract clear first, then add UX around that contract instead of multiplying public tool names too early
• favor tools that can accept explicit topic ids plus bounded intent over inventing separate tools for each tiny topic action
• keep the next milestone focused on operator efficiency: fewer calls, clearer state transitions, and less duplication between command surfaces and LM tool surfaces

Proposed Next Milestone Plan

This plan is intentionally not started yet. It exists to make the next design pass explicit before more topic tools are added.

Current feedback shape:

• one bounded read tool: get_feedback_topic_index
• a few direct file/navigation commands around topics/
• no stable topic contract yet for focused topic reads, bounded mutations, or multi-step topic workflows

Current provenance shape that worked better:

• a small, coherent tool cluster instead of many tiny action tools
• a clearer contract boundary between discovery, execution, and evidence reading
• stronger emphasis on bounded outputs, explicit ids/paths, and evidence-first workflow design

Current design decisions already chosen:

• do not lock the final .topic.md contract before a PoC has been built and pressure-tested
• keep lineage strict rather than heuristic
• topic discovery should auto-resolve across all roots in the current multi-root workspace; if a workspace root contains a top-level topics/ directory, that directory should be treated as a candidate topic source
• a fork creates the next topic iteration in the same directory and copies the parent topic's sibling directory contents forward
• a subtopic lives inside the parent topic's sibling directory as its own .topic.md plus sibling directory pair
• .trace.md artifacts placed inside a topic directory should be discoverable as topic evidence without forcing the tooling to open every trace file eagerly
• the current YouTube feedback UX should be treated as experimental input material rather than as a contract that must be preserved
• the next pass may replace significant parts of that UX if a smaller, more artifact-first, and less tool-heavy model proves clearer

Design signals from the current UX worth preserving only when they still help:

• topics already behave like compound artifacts rather than flat notes: identity, summary, closure, evidence, decisions, role reviews, and timeline all appear as separate meaning-carrying slices
• stale-ness, readiness, and closure alignment appear to matter to operator understanding, but they should only remain first-class if the artifact model needs them explicitly rather than as derived projections
• topic timelines and role-review blocks have clear reading value today, but the PoC should test whether they belong as durable primary state, indexed evidence, or derived views
• the current UX proved there is real provenance value in topic-scoped evidence and review surfaces, but it also suggests the current tool count is too high for the amount of durable truth being carried

Planned next-milestone direction:

1. Define the core topic contract before adding more public tools. Use explicit topic ids, bounded intent, and compact request/result shapes so later tools can share one stable surface instead of each action inventing its own mini-contract.

2. Keep the public feedback surface small. Aim for one strong index/list surface, one strong focused topic-read surface, and one bounded mutation surface family instead of many one-action topic tools.

The index/list surface should discover topic roots automatically across the active multi-root workspace rather than assuming a single repo-local home.

3. Separate operator UX from LM tool count. If the operator needs several UI affordances in VS Code, prefer commands or view actions over multiplying public LM tool names for every small topic interaction.

4. Prefer topic-scoped actions over command-shaped tool sprawl. The better model is likely a smaller set of tools that accept topicId plus a bounded action or intent, rather than separate tools for rename, status flip, note append, evidence attach, summary tweak, and similar micro-operations.

5. Reuse the provenance lesson about evidence-first design. Feedback tooling should make state transitions and supporting evidence easy to inspect after the fact, rather than optimizing only for how many write actions can be exposed quickly.

6. Treat efficiency as a first-class requirement. The next milestone should reduce operator friction, duplicate tool discovery, and repeated context setup, not just increase the raw number of things the extension can do.

7. Prefer artifact simplification over UX preservation. If the current experimental UX implies too many public tools, duplicated actions, or weakly bounded states, simplify the artifact and read/write contract first, then rebuild only the UX that still earns its place.

Open design choices to settle through the PoC:

• whether the lossless rehydration contract should live mainly in a dedicated embedded state block, mainly in the markdown structure itself, or in a hybrid of both
• whether topic evidence should be modeled primarily as explicit indexed references in .topic.md, as directory-discovered artifacts, or as a hybrid model
• what the minimum bounded read surface should be before any broader mutation surface is exposed
• which current UX slices deserve durable first-class representation and which should collapse into derived views or disappear entirely

License

This project is distributed under the Apache License 2.0.

• LICENSE
• NOTICE

Support

If you find this work valuable and want to support its continued development: https://ko-fi.com/Tiinusen